> ## Documentation Index > Fetch the complete documentation index at: https://docs.simpledocs.com/llms.txt > Use this file to discover all available pages before exploring further. # Requests > Create legal requests and track their lifecycle 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](/workflows-guide) 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](/api-reference/requests/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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} curl -X POST https://app.simpledocs.com/api/v1/requests \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "workflow_id=k9Xp2m" \ -F "requester_email=alice@yourcompany.com" \ -F "counterparty_name=Bob Smith" \ -F "counterparty_email=bob@acme.com" \ -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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} curl -X POST https://app.simpledocs.com/api/v1/requests \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "workflow_id=rT7vWx" \ -F "requester_email=alice@yourcompany.com" \ -F "counterparty_signer_name=Bob Smith" \ -F "counterparty_signer_email=bob@acme.com" \ -F "counterparty_name=Acme Corp" \ -F "file=@/path/to/contract.pdf" ``` ### Response ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} { "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](mailto:support@simpledocs.com) 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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} curl -k -X POST https://localhost:3000/api/v1/requests \ -H "Authorization: Bearer YOUR_TOKEN" \ -F "workflow_id=DNxIQK" \ -F "requester_email=alice@yourcompany.com" \ -F "counterparty_name=Bob Smith" \ -F "counterparty_email=bob@acme.com" \ -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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} -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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} curl -X POST https://app.simpledocs.com/api/v1/requests \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "workflow_id=k9Xp2m" \ -F "requester_email=alice@yourcompany.com" \ -F "counterparty_name=Bob Smith" \ -F "counterparty_email=bob@acme.com" \ -F "counterparty_organization_name=Acme Corp" \ -F "internal_signer_email=carol@yourcompany.com" \ -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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} curl -X POST https://app.simpledocs.com/api/v1/requests \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "workflow_id=k9Xp2m" \ -F "requester_email=alice@yourcompany.com" \ -F "counterparty_name=Bob Smith" \ -F "counterparty_email=bob@acme.com" \ -F "counterparty_organization_name=Acme Corp" \ -F "internal_signer_emails[]=carol@yourcompany.com" \ -F "internal_signer_emails[]=eve@yourcompany.com" \ -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](/api-reference/repository-documents/list-repository-documents). | | `declined` | Counterparty declined. | | `canceled` | Request was canceled. | | `expired` | Request expired before completion. | ## Listing requests ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} curl https://app.simpledocs.com/api/v1/requests \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` Filter by status to find active requests: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} curl https://app.simpledocs.com/api/v1/requests/mN3kYq/activity \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} { "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](/webhooks-guide).