v1

latestOpenAPI 3.1.02026-07-17220542.8 KB

Submissions

Create a submission

This API endpoint allows you to create signature requests (submissions) for a document template and send them to the specified submitters (signers). Related Guides <a href="https://www.docuseal.com/guides/send-documents-for-signature-via-api" class="link">Send documents for signature via API</a> <a href="https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api" class="link">Pre-fill PDF document form fields with API</a>

post/submissions

Request body

template_idinteger required

The unique identifier of the template. Document template forms can be created via the Web UI, <a href="https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form" class="link">PDF and DOCX API</a>, or <a href="https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api" class="link">HTML API</a>.

send_emailboolean

Set false to disable signature request emails sending.

send_smsboolean

Set true to send signature request via phone number and SMS.

order'preserved' | 'random'

Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.

completed_redirect_urlstring

Specify URL to redirect to after the submission completion.

bcc_completedstring

Specify BCC address to send signed documents to after the completion.

reply_tostring

Specify Reply-To address to use in the notification emails.

expire_atstring

Specify the expiration date and time after which the submission becomes unavailable for signature.

variablesobject

Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in dynamic template documents.

Example request

{
  "template_id": 1000001,
  "expire_at": "2024-09-01 12:00:00 UTC",
  "variables": {
    "variable_name": "value"
  },
  "submitters": [
    {
      "role": "First Party",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "fields": [
        {
          "name": "First Name",
          "validation": {
            "pattern": "[A-Z]{4}"
          },
          "preferences": {
            "font_size": 12,
            "format": "DD/MM/YYYY",
            "price": 99.99
          }
        }
      ]
    }
  ]
}

Response

idinteger required

Submitter unique ID number.

submission_idinteger required

Submission unique ID number.

uuidstring required

Submitter UUID.

emailstring nullable required

The email address of the submitter.

slugstring required

Unique key to be used in the form signing link and embedded form.

status'completed' | 'declined' | 'opened' | 'sent' | 'awaiting' required

The status of signing request for the submitter.

metadataobject required

Metadata object with additional submitter information.

sent_atstring nullable required

The date and time when the signing request was sent to the submitter.

opened_atstring nullable required

The date and time when the submitter opened the signing form.

completed_atstring nullable required

The date and time when the submitter completed the signing form.

declined_atstring nullable required

The date and time when the submitter declined the signing form.

created_atstring required

The date and time when the submitter was created.

updated_atstring required

The date and time when the submitter was last updated.

namestring nullable required

The name of the submitter.

phonestring nullable required

The phone number of the submitter.

external_idstring nullable required

Your application-specific unique string key to identify this submitter within your app.

rolestring required

The role of the submitter in the signing process.

embed_srcstring required

The src URL value to embed the signing form or sign via a link.