Reference

API reference

Every endpoint the XOsign API exposes. If it is not here, it does not exist.

Machine-readable

This page and /docs/api/openapi.json are generated from the same OpenAPI 3.1 document, so they cannot disagree. Import the JSON into Postman or feed it to a client generator.

Endpoints

Retrieve the current account

GEThttps://xosign.ai/api/v1/account

ScopeNone required

Returns the account behind the API key, plus the key's mode and scopes. The cheapest way to verify a key works and to see what it is allowed to do. Requires no scope.

Responses

Status	Returns	Description
200	Account	The account.
401	Error	The request carried no usable API key, so we could not tell who you are. Codes: missing_authorization, invalid_api_key.
403	Error	We know who you are, but this key or this plan is not allowed to do that. Codes: insufficient_scope, api_access_required.
429	Error	You sent more requests than your plan allows. Carries Retry-After. Codes: rate_limit_exceeded, ip_throttled.
500	Error	Something failed on our side. Nothing is wrong with your request.

See the Account object below for its fields.

List documents

GEThttps://xosign.ai/api/v1/documents

Scopedocuments:read

Your documents, newest first, cursor-paginated. An account with no documents returns an empty list, never a 404. Templates are not included.

Parameters

Name	In	Required	Description
`limit`	query	Optional	How many documents to return, 1–100.defaults to 20 · 1–100
`starting_after`	query	Optional	A cursor from a previous response's `next_cursor`. Returns the page after it. Cannot be combined with `ending_before`.
`ending_before`	query	Optional	A cursor from a previous response. Returns the page before it. Cannot be combined with `starting_after`.
`status`	query	Optional	Comma-separated statuses to include, e.g. `sent,completed`. Any unknown value rejects the whole request. One of: draft, sent, partially_signed, completed, voided, declined, expired, in_review.

Responses

Status	Returns	Description
200	DocumentList	A page of documents.
400	Error	Bad pagination or status filter. Codes: invalid_limit, invalid_cursor, conflicting_cursors, invalid_status.
401	Error	The request carried no usable API key, so we could not tell who you are. Codes: missing_authorization, invalid_api_key.
403	Error	We know who you are, but this key or this plan is not allowed to do that. Codes: insufficient_scope, api_access_required.
429	Error	You sent more requests than your plan allows. Carries Retry-After. Codes: rate_limit_exceeded, ip_throttled.
500	Error	Something failed on our side. Nothing is wrong with your request.

See the DocumentList object below for its fields.

Create a draft document

POSThttps://xosign.ai/api/v1/documents

Scopedocuments:write

Creates a draft and its recipients in one call. Nothing is delivered until you call send.

Field placement is not supported through the API — `content` accepts only the small metadata bag described below, and unknown properties are dropped silently.

Parameters

Name	In	Required	Description
`Idempotency-Key`	header	Optional	Optional but strongly recommended on writes. A client-chosen string of at most 255 characters. Retrying with the same key and the same body replays the original response instead of performing the write twice.max 255 characters

Request body

Field	Type	Required	Description
`title`	string	Required	max 200 characters
`type`	string	Optional	Defaults to `form`.one of 22 values · defaults to form
`primary_language`	string	Optional	one of: en, es · defaults to en
`recipients`	array	Required	1–20 items
`content`	DocumentContent	Optional

Responses

Status	Returns	Description
201	Document	The created draft.
400	Error	The body was rejected. `param` names the exact field. See /docs/api/errors for every code.
401	Error	The request carried no usable API key, so we could not tell who you are. Codes: missing_authorization, invalid_api_key.
403	Error	We know who you are, but this key or this plan is not allowed to do that. Codes: insufficient_scope, api_access_required.
409	Error	Idempotency conflict. Codes: idempotency_key_reused, idempotency_in_progress.
429	Error	You sent more requests than your plan allows. Carries Retry-After. Codes: rate_limit_exceeded, ip_throttled.
500	Error	Something failed on our side. Nothing is wrong with your request.

See the Document object below for its fields.

Retrieve a document

GEThttps://xosign.ai/api/v1/documents/{id}

Scopedocuments:read

Poll this to watch a document progress from `sent` to `completed`.

Parameters

Name	In	Required	Description
`id`	path	Required	The document id.

Responses

Status	Returns	Description
200	Document	The document.
401	Error	The request carried no usable API key, so we could not tell who you are. Codes: missing_authorization, invalid_api_key.
403	Error	We know who you are, but this key or this plan is not allowed to do that. Codes: insufficient_scope, api_access_required.
404	Error	No such document is visible to your account. Also returned for a malformed id and for templates. Code: document_not_found.
429	Error	You sent more requests than your plan allows. Carries Retry-After. Codes: rate_limit_exceeded, ip_throttled.
500	Error	Something failed on our side. Nothing is wrong with your request.

See the Document object below for its fields.

Send a document for signature

POSThttps://xosign.ai/api/v1/documents/{id}/send

Scopedocuments:send

Moves a draft to `sent` and delivers a signature request to each recipient over its channel.

Takes no body — send options come from the `content` you supplied at creation. Only a draft or in-review document can be sent; sending an already-sent document returns `document_not_sendable`.

A test-mode key still transitions the document to `sent` but delivers no email or SMS.

Parameters

Name	In	Required	Description
`id`	path	Required	The document id.
`Idempotency-Key`	header	Optional	Optional but strongly recommended on writes. A client-chosen string of at most 255 characters. Retrying with the same key and the same body replays the original response instead of performing the write twice.max 255 characters

Responses

Status	Returns	Description
200	Document	The document, now `sent`.
400	Error	The document cannot be sent as it stands. Codes: document_not_sendable, no_recipients, no_signers, recipient_contact_required, approver_requires_sequential, pay_app_unsigned.
401	Error	The request carried no usable API key, so we could not tell who you are. Codes: missing_authorization, invalid_api_key.
403	Error	We know who you are, but this key or this plan is not allowed to do that. Codes: insufficient_scope, api_access_required.
404	Error	No such document. Code: document_not_found.
409	Error	Idempotency conflict. Codes: idempotency_key_reused, idempotency_in_progress.
429	Error	You sent more requests than your plan allows. Carries Retry-After. Codes: rate_limit_exceeded, ip_throttled.
500	Error	Something failed on our side. Nothing is wrong with your request.

See the Document object below for its fields.

List a document's recipients

GEThttps://xosign.ai/api/v1/documents/{id}/recipients

Scoperecipients:read

Per-recipient progress: who was sent to, who opened it, who signed, who declined.

This needs its own `recipients:read` scope, separate from `documents:read`, so a key can list documents without reading signer contact details.

Parameters

Name	In	Required	Description
`id`	path	Required	The document id.

Responses

Status	Returns	Description
200	RecipientList	The recipients, ordered by `sign_order`. A document with none returns an empty list.
401	Error	The request carried no usable API key, so we could not tell who you are. Codes: missing_authorization, invalid_api_key.
403	Error	We know who you are, but this key or this plan is not allowed to do that. Codes: insufficient_scope, api_access_required.
404	Error	No such document. Code: document_not_found.
429	Error	You sent more requests than your plan allows. Carries Retry-After. Codes: rate_limit_exceeded, ip_throttled.
500	Error	Something failed on our side. Nothing is wrong with your request.

See the RecipientList object below for its fields.

Objects

The shapes returned by the endpoints above. Every field listed is always present — optional values arrive as null rather than being omitted, so you can read them without guarding for absence.

Document

A document in your account.

Field	Type	Required	Description
`object`	string	Required	one of: document
`id`	string	Required
`type`	string	Required	The kind of document. Determines which workflows apply to it.one of 22 values
`status`	string	Required	one of: draft, sent, partially_signed, completed, voided, declined, expired, in_review
`title`	string	Required
`description`	string or null	Required
`primary_language`	string	Required	one of: en, es
`secondary_language`	string or null	Required
`recipient_count`	integer	Required	How many recipients are on the document.
`sent_at`	string or null	Required
`completed_at`	string or null	Required	Set when every signer has signed.
`voided_at`	string or null	Required
`voided_reason`	string or null	Required
`expires_at`	string or null	Required
`created_at`	string	Required
`updated_at`	string	Required

Recipient

A party on a document. Signing links and any authentication material are never exposed.

Field	Type	Required	Description
`object`	string	Required	one of: recipient
`id`	string	Required
`document_id`	string	Required
`display_name`	string	Required
`email`	string or null	Required
`phone`	string or null	Required
`party_role`	string or null	Required
`channel`	string	Required	one of: email, sms, in_person
`sign_order`	integer	Required
`auth_level`	string	Required	one of: l0_email_link, l1_email_sms_otp, l0_account_session
`status`	string	Required
`sent_at`	string or null	Required
`viewed_at`	string or null	Required
`signed_at`	string or null	Required
`declined_at`	string or null	Required
`declined_reason`	string or null	Required

Account

The account the calling API key belongs to.

Field	Type	Required	Description
`object`	string	Required	one of: account
`id`	string	Required
`display_name`	string	Required
`tier`	string	Required	The account's current plan. Determines your rate limits.
`created_at`	string	Required
`mode`	string	Required	Echoes which kind of key made this request.one of: live, test
`scopes`	array	Required	The scopes granted to the key that made this request.

Errors

Every endpoint can return the shared error envelope. The full catalogue of types and codes is on the errors page.

json

{
  "error": {
    "type": "not_found",
    "code": "document_not_found",
    "message": "No document with that id.",
    "doc_url": "https://xosign.ai/docs/api/errors#not_found",
    "request_id": "req_b07b069f0a83492877e3fa31"
  }
}