List contract requests
Returns all contract signing requests for the authenticated client.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Returns a paginated list of contract signing requests belonging to the authenticated client, newest first. Each item includes the request's current status, the workflow and template it was created from, the linked subject and project, and the full set of participants with their individual signing progress. Supports text search and several filters.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - The caller must hold the
contracts.requests.readpermission and have one of the OWNER, OPERATIONS, or DEVELOPER roles. - The client must have contract signing enabled. If the feature is disabled the request returns
403.
Query parameters
All parameters are optional.
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer (≥ 1) | 1 | Page number. |
page_size | integer (1–200) | 20 | Number of items per page. |
q | string (min length 1) | — | Fuzzy text search across request id, submission slug, current participant key, workflow name, template name, and participant email / display name. |
status | string | — | Filter by contract request status. |
workflow_id | string | — | Return only requests created from this workflow. |
template_version_id | string | — | Return only requests using this template version. |
business_customer_id | string | — | Filter by the business customer subject. |
user_id | string | — | Filter by the registered user subject. |
project_id | string | — | Filter by project. |
created_from | date-time | — | Return requests created at or after this timestamp. |
created_to | date-time | — | Return requests created at or before this timestamp. |
Filters are combined with AND. Results are always ordered by creation time, descending.
Response
200 — Returns a ContractRequestListResponse:
requests— array of contract requests. Each entry carriesid,status,workflow_id,template_version_id,project_id, the subject (user_idorbusiness_customer_id), the linkedtransaction_id, the active stage (current_stage_index,current_participant_key), and theparticipantsarray. Each participant reports itsrole,delivery,status, contact details, signing timestamps, and invitation-email delivery state. Thecompleted_document_urlandaudit_log_urlfields are alwaysnullin this list response; fetch a single request to obtain those download URLs once it is complete.pagination— total count and current page metadata.
Error responses
| Status | When |
|---|---|
403 | Contract signing is disabled for the client. |
422 | A query parameter failed validation (e.g. page < 1, page_size out of range, unknown status value, malformed created_from / created_to). |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.