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 contract flow 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>. - API credentials need the
contracts.requests.readpermission. Dashboard users need the OWNER, OPERATIONS or DEVELOPER role, or a custom role that includes this permission. - Contract signing must be enabled for the client. If it 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) | - | Case-insensitive substring search across request id, current participant key, contract flow name, template name, and participant email / display name. |
status | enum | - | Filter by contract request status. One of created, awaiting_signature, awaiting_transaction_binding, awaiting_transaction, completed, declined, canceled, expired. |
workflow_id | string | - | Return only requests created from this contract flow. |
template_version_id | string | - | Return only requests using this template version. |
business_customer_id | string | - | Filter by business customer: matches requests where it is the request's subject or where any participant signs as that business customer. |
user_id | string | - | Filter by registered user: matches requests where it is the request's subject or where any participant signs as that user. |
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, set only on requests created with the legacy single-subject fields), the linkedtransaction_id, the active stage (current_stage_index,current_participant_key),completion_extra_emails,cc_recipients(each withemail,view_urlandview_expires_at), and theparticipantsarray. Each participant reports itsrole,delivery,status, contact details, signing timestamps, and invitation-email delivery state. A participant'ssigner_url(and the request'sactive_signing_url) is returned only while it is that participant's turn to sign. 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,page,page_sizeandtotal_pages.
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.