# Forms API ## Overview Docue Forms lets you collect information from your customers, partners, or employees through hosted web forms. Each form is backed by a Docue template: when a recipient fills in a form, a document is drafted from that template in your Docue.com workspace, and it can optionally be finalized and sent for signing. The Forms API lets you automate the sending of forms. With the Forms API you can: - List the forms configured for your account. - Send one or more forms to a recipient by email. - Follow the progress of the forms you have sent. **Please note that forms are filled in by the recipient in the Docue Forms UI.** The API does not accept form answers directly. Instead, you create a **form fill**, which invites the recipient by email to fill in the selected forms. If you want to prefill or draft documents programmatically, see the [Platform API](https://developers.docue.com/platform-api). ### Prerequisites To use this API you need a **Forms API key** tied to your Docue Forms account. Forms API keys are separate from Platform API keys. If you do not have one yet, please contact us at [support@docue.com](mailto:support@docue.com). All endpoints require Bearer authentication. Include the API key in the `Authorization` header of every request: ``` Authorization: Bearer docue-fsecret_ ``` The production base URL is `https://forms.docue.com`. All routes are under `/api`. A good first call is [List forms](/forms-api/openapi/forms/getforms): it returns the forms of the account tied to your key and is the simplest way to verify that authentication is configured correctly. See the [API Reference](/forms-api/openapi) for the full list of endpoints. ## Guide > **Core concepts** - **Account** — your Docue Forms account. Your API key belongs to an account, and you can only access that account's forms and form fills. - **Form** — a hosted web form configured by your organization in the Docue Forms admin. Each form is linked to a Docue template (`docue_template_id`). Forms hidden in the admin are not available through the API. - **User** — a member of your Docue Forms account. Every form fill is sent on behalf of a user, identified by their email address (`user_email`). - **Form fill** — an invitation for a recipient to fill in one or more forms. A form fill has an overall `state`, and a state for each of its forms that tracks the recipient's progress. ### Sending forms 1. Call [List forms](/forms-api/openapi/forms/getforms) to find the `id` of each form you want to send. 2. Call [Create a form fill](/forms-api/openapi/form-fills/createformfill) with the recipient's email address, the email address of the user sending the forms, the form ids, and the language of the invitation. Optionally, set `override_sign_method` to use the same signing method for every form. 3. The recipient receives an email with a link to the forms and a PIN code. After entering the PIN code, they fill in the forms, attach any requested files, and sign if the form requires it. 4. When the recipient starts a form, a document is drafted from the form's template in your Docue.com workspace. Call [Get a form fill](/forms-api/openapi/form-fills/getformfill) to follow its progress. If any of the form ids is invalid, for example because the form has been hidden or belongs to another account, the request fails with `422 Unprocessable Entity`. Nothing is created and no email is sent. ```mermaid sequenceDiagram participant App as Integrator participant API as Forms API participant Recipient participant Docue as Docue.com workspace App ->> API: GET /api/forms API -->> App: Forms App ->> API: POST /api/form-fills API -->> App: Form fill (state: new) API ->> Recipient: Invitation email with link and PIN code Recipient ->> API: Opens the link and enters the PIN code Recipient ->> API: Fills in the forms API ->> Docue: Drafts the documents App ->> API: GET /api/form-fills/{id} API -->> App: Form fill (state: completed) ``` ### Form fill states The `state` of a form fill tells whether the recipient has finished: | State | Meaning | | --- | --- | | `new` | The recipient has not completed every form yet. | | `completed` | The recipient has completed every form in the form fill. | Each item in the form fill's `forms` array has its own `state`, which shows the recipient's progress on that form: | State | Meaning | | --- | --- | | `new` | The recipient has not started the form. | | `inProgress` | The recipient has started the form, and a document has been drafted in your Docue.com workspace. | | `completed` | The recipient has completed the form. | Once a form has been started, its `docue_document_id` identifies the drafted document in your Docue.com workspace. You can use it with the [Platform API](/platform-api), for example to download the completed document. There are no webhooks for form fills, so poll [Get a form fill](/forms-api/openapi/form-fills/getformfill) to detect completion. ### Where documents are stored The completed documents are stored in your Docue.com workspace. If the sending user has Docue folders configured, the documents are stored in the first of those folders. Otherwise, the folder configured for the form is used. ### PIN codes and links The link to the forms and the PIN code are sent to the recipient by email only. The API does not return them. ## Responses and pagination Single resources are returned in a `data` object. List endpoints return a `data` array and a `meta` object with pagination details: ```json { "data": [], "meta": { "current_page": 1, "from": null, "last_page": 1, "per_page": 25, "to": null, "total": 0 } } ``` Use the `page` query parameter to select the page, and `per_page` to set the page size. The default page size is 25 and the maximum is 100. ## Limits Requests are rate limited to 60 requests per minute per API key. Each API key has its own limit, even when several keys belong to the same account. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header. ## Feedback If you have questions or feedback about the Forms API, please contact us at [support@docue.com](mailto:support@docue.com).