DocHub

Assign an existing form field to a document role so that role's signer fills it. Side effects: changes field ownership only; never touches the field's value. Works for any field type, including signature fields. Primary use: resolving a PREPARING sign request draft when send validation reports that a recipient "must be assigned at least one field or have annotations enabled" — assigning an unassigned (or wrongly assigned) field to the signer's role clears that blocker. Required inputs: - documentId: the draft's document id (not the template id). - formfieldId: a field id on that document. - documentRoleId: a role id on the same document. If the role does not exist or belongs to a different document, the call fails with a not-found error. Returns: {"status": "success", "formfield": { ... }} — same field shape as the form-field listing, with documentRole updated. Use when: a draft's fields are unassigned or assigned to the wrong recipient. Not for: setting field values, or creating new fields (place those in the DocHub editor).

dochub_assign_formfield

Create a DocHub sign request draft from a template document. Side effects: creates a draft only. No emails are sent to signers until the draft is finalized and sent. Required inputs: - documentId: a template document id (isTemplate=true). - documentRoles: one entry per template role, each with id and email. Role ids come from the template's roles; signer emails come from the user. Name, queue order, and signer type come from the template. Each entry accepts optional canAnnotate: true to grant the role's signer free annotation of the document (write/draw anywhere as free content — it does not make the template's fields fillable for them); omit it to keep the template's stored role configuration. Creation fails with "must be assigned at least one field or have annotations enabled" when a role has neither assigned fields nor annotations — resolvable by re-calling with canAnnotate: true for that role, or by assigning fields to the role in the template (fullUrl). Optional inputs: - title: sign request title. Default: the template document's title. - emailContent: invitation subject and/or body overrides. Any omitted field falls back to its default; omitting emailContent entirely applies both. Default subject: "ACTION NEEDED: {title}". Default body: "Please review, sign, and complete this document." {title} resolves to the effective title (custom if given, otherwise the template title); pass plain values, not pre-interpolated strings. Returns: Success: { "status": "success", "signRequestId": str, "documentUrl": str, "title": str, "emailSubject": str, "emailBody": str } documentUrl is a link to review the draft before it is sent. Use when: starting a role-based sign request from an existing template — sending a templated contract or form out for electronic signature (esign). Not for: regular imported/generated documents.

dochub_create_sign_request_draft_from_template

Create a DocHub sign request from a regular (non-template) document. Side effects: creates a sign request, usually in PREPARING/draft mode when preparingEnabled is true; it is not sent until finalized. Constraint: a regular document can have at most one sign request ever — including one already sent, in progress, or completed. The DocHub API enforces this and rejects a second attempt with a validation error. The existing request appears in the sign-request listing under the same document id. The same content can be reused by copying the document in the DocHub web app, or via a template flow. Required inputs: - documentId: a regular imported/generated document id. - signers: one or more signer email assignments; optional name and queuePosition when provided. Optional canAnnotate (no default) grants the signer free annotation — writing, drawing, or signing anywhere as free content; it does not make form fields fillable, since a field can be completed only by the signer whose role it is assigned to. A PREPARING draft may be created with signers that have neither assigned fields nor the grant — its roles are created with it, and sending stays blocked until every recipient has at least one field or annotations enabled. Immediate sends (preparingEnabled=false) require each signer to carry canAnnotate=true or match an existing role with assigned fields at creation time; older DocHub servers enforce this for drafts as well. Optional inputs: - ownerEntityId: inferred from the authenticated DocHub user when omitted. - title: sign request title. Default: the document's title. - emailContent: invitation subject and/or body overrides. Any omitted field falls back to its default; omitting emailContent entirely applies both. Default subject: "ACTION NEEDED: {title}". Default body: "Please review, sign, and complete this document." {title} resolves to the effective title (custom if given, otherwise the document title); pass plain values, not pre-interpolated strings. - preparingEnabled: defaults to true (review before sending). Returns: Success: { "status": "success", "signRequestId": str, "signRequestStatus": str, "documentUrl": str | null, "documentId": str | null, "signerIds": [str], "title": str, "emailSubject": str, "emailBody": str } DocHub validation errors (signer emails, missing fields, document state) are returned in the response. Use when: sending a regular generated/imported document for signature or esign — "send this for signature", "get this contract e-signed" — when it does not have a sign request yet. Not for: template role-based flows, or a document that already has a sign request (see Constraint).

dochub_create_sign_request_from_document

Set the value of a fillable form field (PUT /api/v2/documents/:document_id/formfields/:formfield_id). Side effects: overwrites the field's current value (idempotent for the same value). Only fields marked ``isFillable: true`` in the form-field listing can be updated: ``ftText`` and ``dhAutoDate`` (string ``value``) or ``ftCheckBox`` (boolean ``value``). Pass ``ffType`` exactly as returned for that field. Permissions: ``isFillable: true`` fields may be filled when ``documentRole`` is null (unassigned) or when ``documentRole.email`` matches the authenticated user's email. Fields assigned to a different email are rejected by the API. Role assignment is not a prerequisite for filling. Returns: {"status": "success", "formfield": { ... }} — same field shape as the form-field listing. After success, present `documentUrl` from the prior form-field listing as a clickable link. Use when: setting text, auto-date display text, or checkbox state on a fillable field — "fill out this form", "complete my part of the document". Not for: non-fillable field types (signatures, radio groups); fields assigned to a different signer.

dochub_fill_formfield

Generate a professional PDF document from a natural-language request — contract, agreement, invoice, lease, NDA, letter, receipt, or a custom type. On success the document is saved to DocHub and its URL and an inline PDF preview are returned. Response `status` is one of: - "needs_more_info": required details are missing. `fields` lists the information still needed; a retry supplies those values in `sourceFacts`, repeats the same `request`, and sets `previousRunId` to the returned `runId`. - "success": contains `documentId`, `documentUrl`, and `pdfUrl`. - "error": contains a user-ready `message` and an `errorCode`. `upgrade_required` means a free/basic-plan limit was reached; `ai_rate_limit_exceeded` means a paid plan's AI allowance is used up; `documentProduced: true` means the PDF was produced but could not be saved to DocHub. Use when: the user asks for any drafted document — "draft a contract", "write up a lease", "make me an invoice". Not for: retrieving or editing existing DocHub documents.

dochub_generate_document

Get the current authenticated user's profile from DocHub. Returns: {"status": "success", "user": {"id": str, "name": str, "email": str, "createdAt": str | null, "entityId": str, "timezone": str | null}} "timezone" is the IANA timezone saved in the user's DocHub preferences; null when unset. Use when: checking who is logged in, verifying authentication, or looking up the saved timezone for presenting timestamps. Not for: looking up other users.

dochub_get_current_user

Get a document from DocHub by its ID. Fetches document metadata and a signed PDF download URL in parallel. Returns: Text JSON: {"status": "success", "document": {"id": str, "title": str, "fullUrl": str | null, "isTemplate": bool, ...}} structured_content: same document fields plus {"pdfUrl": str, "pdfUrlExpiresIn": int} for the PDF viewer widget. Use when: retrieving a specific document by a known ID. Not for: unknown document IDs — find one via a document listing first.

dochub_get_document

Fetch detailed info on a single DocHub sign request. Returns per-signer status, viewedAt / signedAt timestamps, signer emails, and queue positions in addition to the list-view fields. Returns: { "status": "success", "signRequest": { "id": str, "status": str, "createdAt": str, "updatedAt": str, "sender": "me" | "others", "document": {"id": str, "title": str, "fullUrl": str}, "signers": [{ "name": str, "email": str, "isCurrentUser": bool, "status": str, "viewedAt": str | null, "signedAt": str | null, "queuePosition": int | null, }], } } Use when: answering "who hasn't signed yet?", "when did X sign?", or any question needing per-signer timestamps. Not for: listing multiple sign requests.

dochub_get_sign_request

Grant or revoke free document annotation (write/draw anywhere) for a role's signer. Annotation is free-form content only — it does NOT make form fields fillable. A field can be completed only by the signer whose role it is assigned to (via field assignment); granting annotations leaves unassigned fields read-only for the signer. Side effects: changes what the signer is allowed to do in the document. Granting annotations is one way to resolve a send_blocked "must be assigned at least one field or have annotations enabled" finding. Required inputs: - documentId: the document the role belongs to — for a sign request draft, the draft's own documentId, not the template id. - documentRoleId: a role id from a send preview's recipients or a blocker's affectedRecipients. - canAnnotate: true to grant, false to revoke. No default. Returns: {"status": "success", "documentRoleId": str, "canAnnotate": bool} Use when: enabling or disabling free annotation for a signer on a draft. Not for: assigning specific fields to a role.

dochub_update_document_role

List documents from DocHub with optional filters. Supports filtering by title substring, labels (AND logic), privacy level, ownership, date range, and template vs non-template documents. Returns paginated results sorted by createdAt descending by default, so newly created/imported documents appear first. Returns: { "status": "success", "documents": [ { "id": str, "title": str, "fullUrl": str, "isTemplate": bool, "documentRolesData": [ { "id": str, "name": str | null, "email": str | null, "queuePosition": int | null, "signerType": "default" | "in_person", } ], } ], "pagination": { "currentPage": int, "nextPage": int | null, "prevPage": int | null, "totalCount": int, }, "warnings": [str] } warnings: non-fatal notices (for example, label names that were not found and were skipped). Template documents (isTemplate=true) expose documentRolesData role ids used when creating a template-based sign request draft. Use when: searching or browsing documents, filtering by labels/privacy/owner/dates/templates. Not for: looking up a specific document by a known ID.

dochub_list_documents