API referencev2 (preview)

Create an expiry

Preview
posthttps://api.expiryedge.com/v2/expiries
editor or admin60/minIdempotency-Key
Request
curl -X POST 'https://api.expiryedge.com/v2/expiries' \
  -H "Authorization: Bearer $EXPIRYEDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Northwind Dental - State Dental License",
  "type": "License",
  "expiry_date": "2026-10-15",
  "priority": "High",
  "contacts": [
    "c_8Hk2pQ"
  ]
}'
Response
{
  "id": "exp_4Tq9sLm2",
  "name": "Northwind Dental - State Dental License",
  "type": "License",
  "expiry_date": "2026-10-15",
  "start_date": "2025-10-15",
  "priority": "High",
  "state": "todo",
  "notes": "Renew with the State Board of Dentistry at least 30 days ahead.",
  "team_id": "0",
  "contacts": [
    "c_8Hk2pQ"
  ],
  "assigned_to": "u_71bXq",
  "is_done": false,
  "is_archive": false,
  "is_public": false,
  "is_recurring": false,
  "organization_id": "org_northwind",
  "user_id": "u_71bXq",
  "share_token": "5c0e7a52-3f7e-4b3e-9a2e-1d2f0b6c9e11",
  "created_at": "2026-09-27T14:05:00.000Z",
  "updated_at": "2026-09-27T14:05:00.000Z"
}

Same rules as v1 createExpiry (plan limit, referenced contacts/users/folders must be in your organization). Returns 201 with the created expiry and a Location header.

Headers

  • Idempotency-Keystring
    Optional client-generated key (1-255 characters of letters, digits, - _ : .).
    pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body parameters

application/json
  • namestringrequired
    Display name.
  • expiry_datestringrequired
    pattern: ^\d{4}-\d{2}-\d{2}$
  • typestring
    Expiry type name (see getExpiryTypesWithStats).
  • expiry_timezonestring
    IANA timezone for expiry_date when it carries a time.
  • start_datestring | null
  • start_timezonestring
  • prioritystring
    AllowedLowMediumHigh
  • statestring
    Workflow state; defaults to todo.
    Allowedtodoinprogressonholdinreviewcompleted
  • notesstring
  • urlstring
  • document_typestring
  • tagsarray of string
  • team_idstring
    Team id, or '0' for no team.
  • folder_idstring | null
  • assigned_tostring | null
    User id of the assignee (must be in your organization).
  • assigned_bystring
  • contactsarray of string
    Contact ids that receive reminders.
  • directory_entry_idsarray of string
  • is_publicboolean
    Enables the public share link (viewExpiry).
  • share_passwordstring
    Optional password for the share link. Never returned.
  • valuenumber | null
  • penalty_amountnumber | null
  • currencystring | null
    ISO 4217 code, uppercase.
  • custom_columnsobject
  • checklist_itemsarray of objects
  • template_idstring | null
  • template_namestring | null
  • template_fieldsarray of objects | null
  • template_dataobject | null
  • fileUrlsarray of string
  • fileNamesarray of string
  • is_recurringboolean
  • recurrence_typestring | null
    Alloweddayweekmonthyear
  • recurrence_intervalinteger | null
  • recurrence_countinteger | null
  • recurrence_end_datestring | null
  • recurrence_modestring
    Defaults to renew_as_copy.
    Allowedrenew_as_copyrenew_same
  • auto_renewboolean
  • auto_renew_vendorstring | null
  • escalation_enabledboolean
    Always false on create unless explicitly true.
  • escalation_contactsarray of string
  • escalation_notification_daysarray of integer
    Days before expiry at which escalation fires (0-365).

Returns

201
Created.
  • namestring
    Display name.
  • typestring
    Expiry type name (see getExpiryTypesWithStats).
  • expiry_datestring
    Calendar date YYYY-MM-DD in the organization's timezone.
  • expiry_timezonestring
    IANA timezone for expiry_date when it carries a time.
  • start_datestring | null
  • start_timezonestring
  • prioritystring
    AllowedLowMediumHigh
  • statestring
    Workflow state; defaults to todo.
    Allowedtodoinprogressonholdinreviewcompleted
  • notesstring
  • urlstring
  • document_typestring
  • tagsarray of string
  • team_idstring
    Team id, or '0' for no team.
  • folder_idstring | null
  • assigned_tostring | null
    User id of the assignee (must be in your organization).
  • assigned_bystring
  • contactsarray of string
    Contact ids that receive reminders.
  • directory_entry_idsarray of string
  • is_publicboolean
    Enables the public share link (viewExpiry).
  • share_passwordstring
    Optional password for the share link. Never returned.
  • valuenumber | null
  • penalty_amountnumber | null
  • currencystring | null
    ISO 4217 code, uppercase.
  • custom_columnsobject
  • checklist_itemsarray of objects
  • template_idstring | null
  • template_namestring | null
  • template_fieldsarray of objects | null
  • template_dataobject | null
  • fileUrlsarray of string
  • fileNamesarray of string
  • is_recurringboolean
  • recurrence_typestring | null
    Alloweddayweekmonthyear
  • recurrence_intervalinteger | null
  • recurrence_countinteger | null
  • recurrence_end_datestring | null
  • recurrence_modestring
    Defaults to renew_as_copy.
    Allowedrenew_as_copyrenew_same
  • auto_renewboolean
  • auto_renew_vendorstring | null
  • escalation_enabledboolean
    Always false on create unless explicitly true.
  • escalation_contactsarray of string
  • escalation_notification_daysarray of integer
    Days before expiry at which escalation fires (0-365).
  • idstringread-only
  • organization_idstringread-only
  • user_idstringread-only
    Creator's user id.
  • share_tokenstringread-only
  • is_doneboolean
  • completed_atstring | null
    format: date-time
  • is_archiveboolean
    Archived flag (the canonical field name).
  • occurrence_numberintegerread-only
  • is_auto_createdbooleanread-only
  • recurrence_created_from_idstring | nullread-only
  • renewal_historyarray of objectsread-only
  • escalation_notification_sent_daysarray of integerread-only
  • escalation_all_sentbooleanread-only
  • created_atstring
    UTC timestamp, ISO 8601. Every v1 response uses this form, never a raw Firestore Timestamp ({_seconds, _nanoseconds}).
    format: date-time
  • updated_atstring
    UTC timestamp, ISO 8601. Every v1 response uses this form, never a raw Firestore Timestamp ({_seconds, _nanoseconds}).
    format: date-time
  • has_share_passwordbooleanread-only

Errors

400
Invalid parameters or body (VALIDATION_FAILED; details names the fields).
401
Missing, invalid or expired token (UNAUTHORIZED).
403
FORBIDDEN (role / no organization) or PLAN_LIMIT_REACHED (details: current, limit, remaining).
405
Wrong HTTP method for this path; the Allow header lists the valid ones.
409
State or uniqueness conflict: EMAIL_EXISTS (contacts), GROUP_EXISTS (contact groups), CONFLICT (folder name taken), FOLDER_NOT_EMPTY, CLIENT_HAS_PROJECTS, TOO_MANY_ATTACHMENTS, INVALID_STATE (collection request cancel/resend), or IDEMPOTENCY_IN_PROGRESS (same Idempotency-Key still running; see Retry-After).
422
The Idempotency-Key was already used with a different body (IDEMPOTENCY_KEY_REUSED).
429
Too many requests for this endpoint from your IP. Wait Retry-After seconds.