Documents

The forms your org sends out for signature. List templates, send one to an email address, and import each signed form with its receipt and file.

Working with an AI agent?or point it at the Documents markdown or the full-API markdown.

List document templates

GET

/api/v1/documents/templates/list

The forms your org sends out for signature, newest first. Requires documents:read (or :write).

Response:

{
  data: {
    id: string;
    name: string;
    fileName: string;
    sizeBytes: number;
    sha256: string;
    createdAt: number;
  }[]
}

List signature requests

GET

/api/v1/documents/requests/list

Every template sent to an email address that the owner of the token can open, newest first, with its state and, once signed, its receipt: the requests they sent, and the ones shared with them. Pass status=Signed and since=<ms> to import the forms signed after your last run. Requires documents:read (or :write).

Parameter	Type	Description
status	Pending \| Waiting \| Signed \| Declined \| Expired \| Cancelled optional	Only requests in this state.
since	number optional	Only requests updated at or after this time (milliseconds since the epoch).

Response:

{
  data: {
    id: string;
    templateId: string;
    templateName: string;
    fileName: string;
    signingUrl: string;
    recipientEmail: string;
    recipientName: string | null;
    message: string | null;
    status: 'Pending' | 'Waiting' | 'Signed' | 'Declined' | 'Expired' | 'Cancelled';
    packetId: string | null;
    signerOrder: number | null;
    signerCount: number | null;
    contactId: string | null;
    expiresAt: number | null;
    openedAt: number | null;
    remindedAt: number | null;
    decline: { reason: string | null; declinedAt: number } | null;
    signature: {
      legalName: string;
      consentText: string;
      consentVersion: number;
      documentSha256: string;
      signedAt: number;
      ipAddress: string | null;
      userAgent: string | null;
      fieldValues: { fieldId: string; kind: string; label: string; value: string; drawn: boolean }[];
    } | null;
    signedDocumentUrl: string | null;
    createdAt: number;
    updatedAt: number;
  }[]
}

Get a signature request

GET

/api/v1/documents/requests/get

One request that the owner of the token can open, with its receipt and a URL for the exact file that was signed. The URL is short-lived: download it right away. A request that is not shared with the owner reads as not found. Requires documents:read (or :write).

Parameter	Type	Description
id	string required	Request id (from /api/v1/documents/requests/list).

Response:

{
  data: {
    id: string;
    templateId: string;
    templateName: string;
    fileName: string;
    signingUrl: string;
    documentUrl: string | null;
    recipientEmail: string;
    recipientName: string | null;
    message: string | null;
    status: 'Pending' | 'Waiting' | 'Signed' | 'Declined' | 'Expired' | 'Cancelled';
    packetId: string | null;
    signerOrder: number | null;
    signerCount: number | null;
    contactId: string | null;
    expiresAt: number | null;
    openedAt: number | null;
    remindedAt: number | null;
    decline: { reason: string | null; declinedAt: number } | null;
    signature: {
      legalName: string;
      consentText: string;
      consentVersion: number;
      documentSha256: string;
      signedAt: number;
      ipAddress: string | null;
      userAgent: string | null;
      fieldValues: { fieldId: string; kind: string; label: string; value: string; drawn: boolean }[];
    } | null;
    signedDocumentUrl: string | null;
    createdAt: number;
    updatedAt: number;
  }
}

Send a template for signing

POST

/api/v1/documents/requests/send

Email a template to an address with a link to read and sign it. The recipient needs no account. Requires documents:write.

Parameter	Type	Description
templateId	string required	Template id (from /api/v1/documents/templates/list).
email	string optional	The address that receives the signing link. Required unless signers is given.
signers	object optional	A JSON array of signers in signing order, each { email, name?, contactId? }, at most 6. Two or more make a packet: each signer gets the link when the one before has signed, and signs on top of their signature. The response names the first request and the packetId.
name	string optional	The recipient name, used in the email and prefilled on the signing page.
message	string optional	A note that appears in the email and on the signing page.
expiresInDays	number optional	Whole days until the link stops working, 1 to 365. Defaults to 2 (48 hours). Pass null for a link that never expires.
contactId	string optional	The CRM contact this goes to. The send, the signature, and a decline write activities on it. Without it, a contact with the same email is matched.

Response:

{
  data: {
    id: string;
    signingUrl: string;
    status: 'Pending';
    packetId: string | null;
    signerCount: number | null;
  };
  created: true;
}