List Contract Requests

List contract requests

Returns all contract signing requests for the authenticated client.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

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.read permission. 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.

ParameterTypeDefaultDescription
pageinteger (>= 1)1Page number.
page_sizeinteger (1-200)20Number of items per page.
qstring (min length 1)-Case-insensitive substring search across request id, current participant key, contract flow name, template name, and participant email / display name.
statusenum-Filter by contract request status. One of created, awaiting_signature, awaiting_transaction_binding, awaiting_transaction, completed, declined, canceled, expired.
workflow_idstring-Return only requests created from this contract flow.
template_version_idstring-Return only requests using this template version.
business_customer_idstring-Filter by business customer: matches requests where it is the request's subject or where any participant signs as that business customer.
user_idstring-Filter by registered user: matches requests where it is the request's subject or where any participant signs as that user.
project_idstring-Filter by project.
created_fromdate-time-Return requests created at or after this timestamp.
created_todate-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 carries id, status, workflow_id, template_version_id, project_id, the subject (user_id or business_customer_id, set only on requests created with the legacy single-subject fields), the linked transaction_id, the active stage (current_stage_index, current_participant_key), completion_extra_emails, cc_recipients (each with email, view_url and view_expires_at), and the participants array. Each participant reports its role, delivery, status, contact details, signing timestamps, and invitation-email delivery state. A participant's signer_url (and the request's active_signing_url) is returned only while it is that participant's turn to sign. The completed_document_url and audit_log_url fields are always null in this list response; fetch a single request to obtain those download URLs once it is complete.
  • pagination - total, page, page_size and total_pages.

Error responses

StatusWhen
403Contract signing is disabled for the client
422A 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.

Query Params
integer
≥ 1
Defaults to 1

Page number for pagination

integer
1 to 200
Defaults to 20

Number of items per page

length ≥ 1

Fuzzy text search across request id, submission slug, current participant key, and participant email/display name

ContractRequestStatus | null

Filter by contract request status

Filter by workflow id

Filter by template version id

Filter by business customer subject id

Filter by user subject id

Filter by project id

Return requests created at or after this timestamp

Return requests created at or before this timestamp

Responses

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json