Sign in
Signing Requests

Create and Send Signing Request (Atomic)

Create and immediately send a signing request in a single atomic operation. This endpoint combines the functionality of POST /signing-requests and POST /signing-requests/{id}/send.

Key Benefits:

  • Single API call instead of two separate requests
  • Validates all send requirements BEFORE creating the signing request
  • Atomic credit deduction - only charges if everything succeeds
  • Returns status: 'sent' immediately with first signer details
  • More efficient (saves 1 API call + round-trip time)

Validation:

  • All standard creation validations (document/template, recipients, fields)
  • Additional send validations:
    • All signers must have first_name and valid email
    • Required read-only fields must have final_value populated
    • Prefilled data fields (variable_name) must have corresponding user data
    • Company must have sufficient credits (≥1)

Atomicity:

  • If any validation fails, nothing is created
  • Credit is only deducted after successful creation and before email send
  • If email send fails after creation, signing request remains in 'draft' status and credit is NOT deducted

Temporary ID Pattern: For document-based creation, use temporary IDs (format: 'temp_X') to reference recipients before creation. The API validates all references and automatically maps temporary IDs to real UUIDs.

Rate Limit: 120 requests/minute (same as write operations)

post/signing-requests/create-and-send

Request body

OR

Example request

{
  "name": "Employment Contract - John Doe",
  "description": "Full-time employment contract for Software Engineer position",
  "document": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...",
  "template_id": "123e4567-e89b-12d3-a456-426614174000",
  "expiration_hours": 168,
  "fields": [
    {
      "recipient_id": "temp_signer_1",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 200,
      "width": 200,
      "height": 50,
      "variable_name": "phone_number",
      "final_value": "Software Engineer",
      "background_color": "#FFFDE7"
    }
  ],
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "background_color": "#FFFDE7",
      "font_size": 12
    }
  ],
  "reminders": [
    {
      "hours_before_expiration": 24
    }
  ],
  "settings": {
    "identity_editable_fields": [
      "name",
      "company"
    ]
  },
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "completion_title": "Thank you for signing",
  "completion_message": "Your signed copy is on its way to your inbox.",
  "completion_redirect_url": "https://example.com/thank-you",
  "completion_redirect_delay": 5
}

Response

Signing request created and sent successfully. The response may include non-blocking anchor-tag warnings.

idstring uuid required

Signing request ID

namestring required

Signing request name

descriptionstring nullable

Signing request description

status'sent' required

Always 'sent' for this endpoint

document_urlstring uri

Signed URL to access document

page_countinteger

Number of pages in document

expiration_hoursinteger

Hours until expiration

created_datestring date-time
sent_datestring date-time

When request was sent

template_idstring uuid nullable
credits_remaininginteger

Company credits remaining after deduction

warningsstring[]

Optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

Example response

{
  "fields": [
    {
      "format_rules": {
        "dateFormat": "MMMM dd, yyyy"
      },
      "background_color": "#FFFDE7"
    }
  ]
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.