JustDocs Developers

Appearance

Send an intake link ​

POST /api/v1/intake-requests

Needs the send permission.

Permissionsend
MCP toolcreate_intake_request
RetriesSafe with an Idempotency-Key
ApprovalAgent keys, and keys made to need approval, wait for an owner or admin: 202

Request ​

Headers ​

NameTypeRequiredDescription
Idempotency-KeystringNoMakes a retried call safe: the same key returns the first result instead of creating or sending again. Matches ^[A-Za-z0-9_-]{8,100}$.

Body ​

An intake link: a named person without an account answers a form, and their answers fill the documents.

FieldTypeRequiredDescription
titlestringNo1–255 characters.
messagestringNoUp to 2,000 characters.
documentsarray of objectsYes1–10 items.
documents[].document_idstring (uuid)Yes—
documents[].draft_revisionintegerYesAt least 1.
respondentobjectYes—
respondent.namestringYes1–200 characters.
respondent.emailstring (email)YesUp to 255 characters.
expires_in_daysintegerNo1–60. Default 14.
afterreview or signNoAfter they answer: the sender reviews first, or the respondent goes straight on to sign (give signing). Default review.
signingobjectNo—
signing.respondent_rolestringYesMatches ^[a-z0-9][a-z0-9-]{0,39}$.
signing.recipientsarray of objectsNoUp to 19 items.
signing.recipients[].role_keystringYesThe role this person signs as, matching the documents' roles. Matches ^[a-z0-9][a-z0-9-]{0,39}$.
signing.recipients[].namestringYes1–200 characters.
signing.recipients[].emailstring (email)YesUp to 255 characters.
signing.routingsequential or parallelNoDefault sequential.
signing.expires_in_daysintegerNo1–365. Default 30.

Responses ​

StatusMeaning
201Created and emailed to the respondent.
202Waits for a person's approval.
400The input is invalid.
401No key, or a key that is unknown, expired or revoked, or whose creator is no longer an owner or admin.
402The workspace's plan doesn't allow it: no completed requests left this month, more members than sender seats, more signers than the plan allows, a document that must be bought first, or the workspace's saved templates are at its plan's limit.
403The key lacks the permission, or it is an API key and the workspace isn't on Teams & Platform.
404Not found in the key's workspace (a key works only in the workspace it was made in; get_workspace says which).
409The request is in a state that doesn't allow this, or the Idempotency-Key was used for something else.
422Valid, but it can't go ahead: an address outside the key's recipient domains or one that can't receive email, or a signing role without a recipient.
429More than 120 calls a minute through this key, more than 2000 from one network address (for IPv6, its /56 block) across all keys, or a limit on sending reached: the key's daily sends, the plan's or a recipient's daily requests, or the workspace's waiting approvals.

Errors share one shape, { "message": "…" }: see Errors and rate limits.

201 body ​

FieldTypeDescription
idstring (uuid)—
titlestring or null—
messagestring or null—
statusopen or submitted or voided or expired—
afterreview or sign—
respondentobject—
respondent.namestring—
respondent.emailstring—
document_idsarray of string (uuid)—
signing_request_idstring or null—
submitted_atstring (date-time) or null—
expires_atstring (date-time) or null—
created_atstring (date-time) or null—
answersobject or null—
Example
json
{
  "id": "e7b2d4f6-8a1c-4e3b-9d5f-7a2c4e6b8d1f",
  "title": "Your details for the NDA",
  "message": null,
  "status": "submitted",
  "after": "review",
  "respondent": {
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "document_ids": [
    "8a1f5c2e-3b4d-4e6f-9a7b-1c2d3e4f5a6b"
  ],
  "signing_request_id": null,
  "submitted_at": "2026-11-04T10:02:31.000Z",
  "expires_at": "2026-11-17T16:20:00.000Z",
  "created_at": "2026-11-03T16:20:00.000Z",
  "answers": {
    "client_name": "Acme Inc.",
    "effective_date": "2026-11-03"
  }
}

202 body ​

FieldTypeDescription
statusawaiting_approval—
approvalobject—
approval.idstring (uuid)—
approval.kindsigning.send or intake.create—
approval.statuspending or approved or declined or expired or failed—
approval.titlestring—
approval.addressesarray of string—
approval.credentialstring or null—
approval.signing_request_idstring or null—
approval.intake_request_idstring or null—
approval.decided_bystring or null—
approval.decided_atstring (date-time) or null—
approval.resultstring or null—
approval.expires_atstring (date-time)—
approval.created_atstring (date-time)—
Example
json
{
  "status": "awaiting_approval",
  "approval": {
    "id": "a4c6e8b2-1d3f-4b5a-8c7e-9f1b3d5a7c2e",
    "kind": "signing.send",
    "status": "approved",
    "title": "Mutual NDA — Acme",
    "addresses": [
      "ada@example.com"
    ],
    "credential": "Sales agent",
    "signing_request_id": "c3e9a7b1-2d4f-4a6c-8e1b-5f7d9a2c4e6b",
    "intake_request_id": null,
    "decided_by": "Olga Owner",
    "decided_at": "2026-11-03T16:41:10.000Z",
    "result": null,
    "expires_at": "2026-11-10T16:20:01.000Z",
    "created_at": "2026-11-03T16:20:01.000Z"
  }
}

Examples ​

bash
curl -X POST https://tryjustdocs.com/api/v1/intake-requests \
  -H "Authorization: Bearer $JUSTDOCS_API_KEY" \
  -H "Idempotency-Key: deal-4821-create-intake-request" \
  -H "Content-Type: application/json" \
  -d '{
  "documents": [
    {
      "document_id": "8a1f5c2e-3b4d-4e6f-9a7b-1c2d3e4f5a6b",
      "draft_revision": 1
    }
  ],
  "respondent": {
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "after": "review"
}'
js
const response = await fetch("https://tryjustdocs.com/api/v1/intake-requests", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JUSTDOCS_API_KEY}`,
    "Idempotency-Key": "deal-4821-create-intake-request",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    documents: [
      {
        document_id: "8a1f5c2e-3b4d-4e6f-9a7b-1c2d3e4f5a6b",
        draft_revision: 1
      }
    ],
    respondent: {
      name: "Ada Lovelace",
      email: "ada@example.com"
    },
    after: "review"
  }),
});
if (!response.ok) throw new Error((await response.json()).message);
const result = await response.json();
python
import os
import requests

response = requests.post(
    "https://tryjustdocs.com/api/v1/intake-requests",
    headers={"Authorization": f"Bearer {os.environ['JUSTDOCS_API_KEY']}", "Idempotency-Key": "deal-4821-create-intake-request"},
    json={
        "documents": [
            {
                "document_id": "8a1f5c2e-3b4d-4e6f-9a7b-1c2d3e4f5a6b",
                "draft_revision": 1,
            },
        ],
        "respondent": {
            "name": "Ada Lovelace",
            "email": "ada@example.com",
        },
        "after": "review",
    },
    timeout=30,
)
response.raise_for_status()
result = response.json()