Requests - SimpleDocs

A request is a legal document process initiated against a workflow. Once created, it moves through a series of statuses as it is reviewed, signed, and completed.

Before you start

You will need:

A published workflow ID — see the Workflows guide
The workflow schema — to know which fields and variables are required
A token with the write scope

Creating a request

Use the Create request endpoint. The required fields depend on the workflow schema.

Example: Generated document workflow

For a workflow that generates an agreement from a template (e.g. an NDA), you need to provide counterparty details and workflow variables:

curl -X POST https://app.simpledocs.com/api/v1/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "workflow_id=k9Xp2m" \
  -F "[email protected]" \
  -F "counterparty_name=Bob Smith" \
  -F "[email protected]" \
  -F "counterparty_organization_name=Acme Corp" \
  -F 'variables={"purpose": "To agree on confidential", "duration_unit": "year", "duration": 2}'

Example: Third-party document workflow

For a workflow that accepts an uploaded document, provide the file along with counterparty details:

curl -X POST https://app.simpledocs.com/api/v1/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "workflow_id=rT7vWx" \
  -F "[email protected]" \
  -F "counterparty_signer_name=Bob Smith" \
  -F "[email protected]" \
  -F "counterparty_name=Acme Corp" \
  -F "file=@/path/to/contract.pdf"

Response

{
  "data": {
    "id": "mN3kYq",
    "type": "legal_request",
    "attributes": {
      "name": "NDA — Mutual — Acme Corp",
      "status": "draft"
    }
  }
}

requester_email is required. It must match an existing user in your company.

Creating a Request with Support Documents

Check the optional_fields array in the workflow schema response before submitting — it lists what the workflow accepts. Supporting documents are additional files attached to a request alongside the main legal document. You can attach files in any format (PDF, Word, images, spreadsheets, etc.), up to 100 MB per file.

Merging supporting documents

When merging is enabled, supporting documents are appended to the main legal request document and delivered as a single combined PDF to all parties. This is useful when you want annexes, exhibits, or reference materials to be part of the signed record. Only PDF and Word (.docx) files can be merged. Files in other formats can still be attached as supporting documents but will not be included in the merge.

merge_documents_into_pdf only appears in optional_fields when the feature is enabled for your account. Contact support to request access.

support_documents[] accepts one or more file uploads (any format, max 100 MB each).
merge_documents_into_pdf must be "true" to merge supporting PDF and Word documents into the main document; any other value (including omitting the field) is treated as false.

curl -k -X POST https://localhost:3000/api/v1/requests \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "workflow_id=DNxIQK" \
  -F "[email protected]" \
  -F "counterparty_name=Bob Smith" \
  -F "[email protected]" \
  -F "counterparty_organization_name=Acme Corp" \
  -F 'variables={"purpose": "To agree on confidential terms", "duration_unit": "year", "duration": 2}' \
  -F "support_documents[]=@@/path/to/file.pdf" \
  -F "merge_documents_into_pdf=true"

To attach multiple support documents, repeat the support_documents[] flag:

  -F "support_documents[]=@/path/to/first.pdf" \
  -F "support_documents[]=@/path/to/second.pdf"

Selecting an internal signer

How you specify internal signers depends on the workflow configuration. If the workflow has only one configured signer, no signer field is required — the signer is assigned automatically.

Single signer

For workflows with a single internal signer, pass the signer’s email as internal_signer_email.

Check fields_properties.internal_signer_email.properties.options in the workflow schema for the list of available signer emails.

curl -X POST https://app.simpledocs.com/api/v1/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "workflow_id=k9Xp2m" \
  -F "[email protected]" \
  -F "counterparty_name=Bob Smith" \
  -F "[email protected]" \
  -F "counterparty_organization_name=Acme Corp" \
  -F "[email protected]" \
  -F 'variables={"purpose": "To agree on confidential terms", "duration_unit": "year", "duration": 2}'

Multiple signers

When internal_signer_emails[] appears in required_fields, pass one entry per signer in signing order:

curl -X POST https://app.simpledocs.com/api/v1/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "workflow_id=k9Xp2m" \
  -F "[email protected]" \
  -F "counterparty_name=Bob Smith" \
  -F "[email protected]" \
  -F "counterparty_organization_name=Acme Corp" \
  -F "internal_signer_emails[][email protected]" \
  -F "internal_signer_emails[][email protected]" \
  -F 'variables={"purpose": "To agree on confidential terms", "duration_unit": "year", "duration": 2}'

Position in the array determines signing order. Adobe Sign notifies signers sequentially — position 1 signs first, then position 2. DocuSign and Dropbox Sign deliver the document to all signers simultaneously, regardless of order.

Check fields_properties.internal_signer_emails[].properties.options in the workflow schema for the list of available signer emails.

Request statuses

Requests move through the following statuses:

Status	Description
`draft`	Request created, not yet submitted.
`ready_for_send`	Ready to be sent to the counterparty.
`business_review`	Under internal business review.
`initial_review`	Under legal review.
`ongoing_review`	Under business review.
`sent_for_signature`	Sent to counterparty for signature.
`changes_proposed`	Counterparty has proposed changes.
`signed`	All parties have signed.
`archived`	Request has completed its cycle. The signed document is available in Repository Documents.
`declined`	Counterparty declined.
`canceled`	Request was canceled.
`expired`	Request expired before completion.

Listing requests

curl https://app.simpledocs.com/api/v1/requests \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filter by status to find active requests:

curl "https://app.simpledocs.com/api/v1/requests?status=sent_for_signature" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Getting a request

Retrieve a single request by its ID:

curl https://app.simpledocs.com/api/v1/requests/mN3kYq \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Tracking activity

The activity log records every status change, comment, and action on a request:

curl https://app.simpledocs.com/api/v1/requests/mN3kYq/activity \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "1",
      "type": "activity_log",
      "attributes": {
        "action": "status_change",
        "description": "Status changed to initial_review",
        "comment": null,
        "created_at": "2026-03-05T15:00:00Z"
      }
    }
  ]
}

To receive real-time notifications when a request is fully executed, set up a webhook.

​Before you start

​Creating a request

​Example: Generated document workflow

​Example: Third-party document workflow

​Response

​Creating a Request with Support Documents

​Merging supporting documents

​Selecting an internal signer

​Single signer

​Multiple signers

​Request statuses

​Listing requests

​Getting a request

​Tracking activity

Before you start

Creating a request

Example: Generated document workflow

Example: Third-party document workflow

Response

Creating a Request with Support Documents

Merging supporting documents

Selecting an internal signer

Single signer

Multiple signers

Request statuses

Listing requests

Getting a request

Tracking activity