API reference

docuinked has 29 tools. Each is a REST route and an MCP tool from one registry, so this page can't drift from the product.

Base URL: https://docuinked.com. Send your key as Authorization: Bearer di_test_.... Bodies are JSON. The machine-readable copy is the OpenAPI file.

Every success looks like this:

{"status": "ok", "request_id": "req_...", "data": {}}

Path parameters such as {id} go in the URL. On GET routes, other fields are query parameters. Write calls take an Idempotency-Key header of up to 200 characters. The same key returns the first result and does not repeat the work. Limit: 120 requests a minute per key. See errors for failures.

whoami

Check connection. Confirms the connection works. Shows the account name, whether it is in test mode (no email is ever sent) or live, and the daily limit on live sends.

GET /v1/whoami

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

create_document

Create a document. Creates a draft from a PDF (pdf_url, pdf_base64, or several files) with signers and fields. Fields go after anchor text, on {{signature:1}} tags in the PDF, or at page coordinates; with none, fields go on the PDF's own Signature, Date and Name lines (one signer per signature line, placement: labels), or else one signature field per signer on the last page. Returns draft_hash, review_url, warnings and next_action. Sending is a separate step: send_document with the draft_hash. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/documents

{
  "additionalProperties": false,
  "properties": {
    "consumer_disclosure": {
      "description": "Signers are consumers: shows the ESIGN consumer disclosure and asks them to open a test PDF. Default false.",
      "type": "boolean"
    },
    "expires_in_days": {
      "description": "Default 30.",
      "maximum": 365,
      "minimum": 1,
      "type": "integer"
    },
    "fields": {
      "description": "Leave out to use the PDF's Signature, Date and Name lines, or else one signature field per signer on the last page.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "anchor": {
            "description": "Text in the PDF to place the field just after, such as 'Signature:'. Easier than coordinates.",
            "type": "string"
          },
          "h": {
            "description": "Height as a fraction of page height. Has a sensible default per kind.",
            "type": "number"
          },
          "kind": {
            "enum": [
              "signature",
              "initials",
              "date",
              "name",
              "text",
              "checkbox",
              "dropdown",
              "radio",
              "attachment"
            ]
          },
          "label": {
            "description": "Shown to the signer, such as 'Upload a photo ID'.",
            "maxLength": 80,
            "type": "string"
          },
          "options": {
            "description": "Choices for dropdown and radio fields.",
            "items": {
              "maxLength": 60,
              "type": "string"
            },
            "maxItems": 20,
            "type": "array"
          },
          "page": {
            "description": "Needed with x and y. Left out when using anchor.",
            "minimum": 1,
            "type": "integer"
          },
          "required": {
            "type": "boolean"
          },
          "signer": {
            "description": "1 for the first signer in the list, 2 for the second.",
            "minimum": 1,
            "type": "integer"
          },
          "w": {
            "description": "Width as a fraction of page width. Has a sensible default per kind.",
            "type": "number"
          },
          "x": {
            "description": "Left edge as a fraction of page width.",
            "maximum": 1,
            "minimum": 0,
            "type": "number"
          },
          "y": {
            "description": "Top edge as a fraction of page height.",
            "maximum": 1,
            "minimum": 0,
            "type": "number"
          }
        },
        "required": [
          "signer",
          "kind"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "files": {
      "description": "Several PDFs or images joined into one document, in order. Each item has url or base64.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "base64": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "maxItems": 20,
      "type": "array"
    },
    "message": {
      "description": "Note shown in the signing email.",
      "maxLength": 2000,
      "type": "string"
    },
    "metadata": {
      "description": "Your own keys and values, returned on reads and webhooks' document lookups.",
      "type": "object"
    },
    "ordered": {
      "description": "Sign one at a time in list order.",
      "type": "boolean"
    },
    "pdf_base64": {
      "type": "string"
    },
    "pdf_url": {
      "description": "Public https link to the PDF.",
      "type": "string"
    },
    "reminder_every_days": {
      "description": "0 turns reminders off. Default 3.",
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    },
    "send": {
      "description": "Also send, under this key's send policy. Default false.",
      "type": "boolean"
    },
    "signers": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "access_code": {
            "description": "Optional code shared with the signer outside email.",
            "type": "string"
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "name": {
            "maxLength": 120,
            "type": "string"
          },
          "role": {
            "description": "cc gets the finished copy and never signs. Default signer.",
            "enum": [
              "signer",
              "cc"
            ]
          }
        },
        "required": [
          "name",
          "email"
        ],
        "type": "object"
      },
      "maxItems": 10,
      "minItems": 1,
      "type": "array"
    },
    "title": {
      "maxLength": 200,
      "type": "string"
    }
  },
  "required": [
    "title",
    "signers"
  ],
  "type": "object"
}

send_document

Send for signature. Asks to send a draft to its signers. The draft_hash must match the current draft. With an agent key or an MCP connection, nothing is sent: it creates an approval request and returns approval_url, and the document goes out only after a named person approves that exact draft (in test mode, simulate_approval can stand in for the person). In test mode no email is sent, signers at sign@test.docuinked.com or decline@test.docuinked.com act at once, and signing links come back. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/documents/{id}/send

{
  "additionalProperties": false,
  "properties": {
    "draft_hash": {
      "description": "From create_document. Refuses if the draft has changed since. Required for agent keys.",
      "type": "string"
    },
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

list_documents

List documents. Lists documents in the current mode (test or live), newest first, with each signer's status. Filter by status; limit is 1 to 100.

GET /v1/documents

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "starting_after": {
      "description": "Pass next_starting_after from the previous page.",
      "type": "string"
    },
    "status": {
      "enum": [
        "draft",
        "pending_approval",
        "sent",
        "sealing",
        "completed",
        "declined",
        "voided",
        "expired"
      ]
    },
    "updated_since": {
      "description": "Only documents changed since this time.",
      "format": "date-time",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

get_document

Get a document. Shows one document's status, each signer's progress and its review link.

GET /v1/documents/{id}

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

get_signed_pdf

Get the signed PDF. Returns the sealed, signed PDF as base64 with its SHA-256, once the document is completed. The file can be large.

GET /v1/documents/{id}/signed_pdf

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

get_original_pdf

Get the original PDF. Returns the document as it was uploaded, before any signature, as base64 with its SHA-256. Use it to preview a draft or a document in progress.

GET /v1/documents/{id}/original_pdf

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

get_evidence

Get the evidence record. Returns the full audit trail: every event, its hash chain, and the seal certificate.

GET /v1/documents/{id}/evidence

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

remind_signers

Remind signers. Emails a reminder now to every signer of a sent document who hasn't signed yet. Returns how many were reminded. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/documents/{id}/remind

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

void_document

Void a document. Cancels a sent document that is still waiting for signatures, so it can no longer be signed. This can't be undone. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/documents/{id}/void

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    },
    "reason": {
      "description": "Optional. Kept in the evidence log and shown in the document's history.",
      "maxLength": 500,
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

create_signing_link

Create a signing link. Makes a signing link for one signer of a sent document, for your own app or message. With embed true it returns embed_url for an iframe on a site listed in your branding. Anyone holding the link can sign as that signer. Live agent keys and MCP connections can't create links for live documents. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/documents/{id}/signing_links

{
  "additionalProperties": false,
  "properties": {
    "embed": {
      "type": "boolean"
    },
    "id": {
      "type": "string"
    },
    "signer": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "id",
    "signer"
  ],
  "type": "object"
}

simulate_approval

Simulate the approval (test). Test mode only. Approves a test document's pending approval as the account's person would, then sends it, so CI and agent evals can run the approval step unattended. Live documents always need a person to approve at approval_url. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/test/documents/{id}/approve

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

simulate_signer

Simulate a signer (test). Test mode only. Signs or declines as one signer (signer is their position, from 1) so a whole flow runs without a browser. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/test/documents/{id}/simulate

{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "sign",
        "decline"
      ]
    },
    "id": {
      "type": "string"
    },
    "signer": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "id",
    "signer",
    "action"
  ],
  "type": "object"
}

update_signer

Fix a recipient. Corrects the name or email of someone who hasn't signed yet, on a sent document. Old links stop working and a new request goes to the new address. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/documents/{id}/signers/{position}

{
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "maxLength": 120,
      "type": "string"
    },
    "position": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "position"
  ],
  "type": "object"
}

bulk_send

Bulk send a template. Creates and sends one document per recipient set from a template, up to 100 at a time. With agent keys and MCP connections, each live document waits for its own approval. Over REST, an Idempotency-Key makes retries safe. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/templates/{id}/bulk

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    },
    "recipients": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "metadata": {
            "type": "object"
          },
          "signers": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "access_code": {
                  "description": "Optional code shared with the signer outside email.",
                  "type": "string"
                },
                "email": {
                  "format": "email",
                  "type": "string"
                },
                "name": {
                  "maxLength": 120,
                  "type": "string"
                },
                "role": {
                  "description": "cc gets the finished copy and never signs. Default signer.",
                  "enum": [
                    "signer",
                    "cc"
                  ]
                }
              },
              "required": [
                "name",
                "email"
              ],
              "type": "object"
            },
            "maxItems": 10,
            "minItems": 1,
            "type": "array"
          },
          "title": {
            "maxLength": 200,
            "type": "string"
          }
        },
        "required": [
          "signers"
        ],
        "type": "object"
      },
      "maxItems": 100,
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "id",
    "recipients"
  ],
  "type": "object"
}

test_webhook

Send a test event. Sends a signed test event to the webhook right away and reports what the endpoint answered. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/webhooks/{id}/test

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

list_webhook_deliveries

Webhook delivery log. The last 50 delivery attempts for a webhook: event, status code, error and time taken.

GET /v1/webhooks/{id}/deliveries

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

get_attachment

Get a signer's upload. Returns a file a signer uploaded, as base64, with its name, type and SHA-256. Field IDs are listed in get_evidence.

GET /v1/documents/{id}/attachments/{field}

{
  "additionalProperties": false,
  "properties": {
    "field": {
      "type": "string"
    },
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "field"
  ],
  "type": "object"
}

delete_document

Delete a document. Permanently deletes a document that isn't in progress: its encryption key is destroyed, so its files can never be read again. The evidence log keeps a record that it existed. Not available to agent keys. Send an Idempotency-Key header so a retry can't repeat the work.

DELETE /v1/documents/{id}

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

create_template

Save as a template. Makes a reusable template from a draft or finished document: same file, fields and signer roles, with names and emails cleared. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/documents/{id}/template

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "maxLength": 200,
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

get_branding

Get branding. Shows the account's signer-facing name, accent colour, logo, embed origins and whether docuinked branding is hidden.

GET /v1/branding

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

update_branding

Update branding. Sets what signers see: your name, accent colour, logo, and the sites allowed to embed signing. Fields you leave out stay as they are. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/branding

{
  "additionalProperties": false,
  "properties": {
    "accent_color": {
      "pattern": "^#[0-9A-Fa-f]{6}$",
      "type": "string"
    },
    "display_name": {
      "maxLength": 80,
      "type": "string"
    },
    "embed_origins": {
      "description": "Sites allowed to frame signing, like https://app.example.com.",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "type": "array"
    },
    "hide_docuinked_branding": {
      "type": "boolean"
    },
    "logo_png_base64": {
      "description": "PNG under 200 KB.",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

create_account

Create a sub-account. For platforms: makes an account for one of your customers. Act for it on any call with the header DocuInked-Account and your own key. Each has its own documents, branding and webhooks. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/accounts

{
  "additionalProperties": false,
  "properties": {
    "name": {
      "maxLength": 120,
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "type": "object"
}

list_accounts

List sub-accounts. Lists the sub-accounts this account manages, for platforms.

GET /v1/accounts

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

list_templates

List templates. Lists reusable templates with their IDs and signer roles, for create_from_template.

GET /v1/templates

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

create_from_template

Start from a template. Creates a draft from a template, filling its signer roles in order. Nothing is sent. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/templates/{id}/documents

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    },
    "signers": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "access_code": {
            "description": "Optional code shared with the signer outside email.",
            "type": "string"
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "name": {
            "maxLength": 120,
            "type": "string"
          },
          "role": {
            "description": "cc gets the finished copy and never signs. Default signer.",
            "enum": [
              "signer",
              "cc"
            ]
          }
        },
        "required": [
          "name",
          "email"
        ],
        "type": "object"
      },
      "maxItems": 10,
      "minItems": 1,
      "type": "array"
    },
    "title": {
      "maxLength": 200,
      "type": "string"
    }
  },
  "required": [
    "id",
    "signers"
  ],
  "type": "object"
}

create_webhook

Add a webhook. Registers an https URL for events such as document.completed. Returns the signing secret once. Send an Idempotency-Key header so a retry can't repeat the work.

POST /v1/webhooks

{
  "additionalProperties": false,
  "properties": {
    "events": {
      "description": "Only these events. Leave out for all.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "url": {
      "type": "string"
    }
  },
  "required": [
    "url"
  ],
  "type": "object"
}

list_webhooks

List webhooks. Lists active webhooks.

GET /v1/webhooks

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

delete_webhook

Remove a webhook. Stops sending events to a webhook. Send an Idempotency-Key header so a retry can't repeat the work.

DELETE /v1/webhooks/{id}

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}