> ## Documentation Index > Fetch the complete documentation index at: https://docs.synthetic.ai/llms.txt > Use this file to discover all available pages before exploring further. # List contracts > Lists contracts, oldest first. Page with `limit` and the cursors from the previous page; `hasMore` says whether more rows lie in the direction being read. Keep the same filters for the whole run. Needs a key holding `contracts:read`. ## OpenAPI ````yaml https://app.synthetic.ai/api/v1/openapi.json get /contracts openapi: 3.1.0 info: title: Synthetic API description: Read access to your Synthetic data. version: 0.1.0 servers: - url: https://app.synthetic.ai/api/v1 security: [] paths: /contracts: get: tags: - Contracts summary: List contracts description: >- Lists contracts, oldest first. Page with `limit` and the cursors from the previous page; `hasMore` says whether more rows lie in the direction being read. Keep the same filters for the whole run. Needs a key holding `contracts:read`. operationId: contracts-list parameters: - in: query name: customerIds schema: description: Only the contracts of these customers, separated by commas. type: string - in: query name: lifecycleStatuses schema: description: >- Only contracts whose lifecycleStatus is one of these, separated by commas — for example DRAFT,ACTIVE. The statuses are DRAFT, ACTIVE, EXPIRED, CANCELLED, DELETED. Leave it out for every status but DELETED. type: string - in: query name: processingInvoices schema: description: >- true for only the contracts whose processingInvoices is true; false for only the rest. type: boolean - in: query name: startingAfter schema: type: string minLength: 1 maxLength: 1024 pattern: ^[A-Za-z0-9._-]+$ description: The nextCursor of the previous page, to read the page after it. - in: query name: endingBefore schema: type: string minLength: 1 maxLength: 1024 pattern: ^[A-Za-z0-9._-]+$ description: The prevCursor of the previous page, to read the page before it. - in: query name: limit schema: default: 50 description: Rows per page, 1 to 100. type: integer minimum: 1 maximum: 100 responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Contract' hasMore: type: boolean nextCursor: type: string prevCursor: type: string required: - data - hasMore additionalProperties: false '400': description: Input validation failed content: application/json: schema: $ref: '#/components/schemas/error.BAD_REQUEST' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/error.UNAUTHORIZED' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR' security: - BearerAuth: [] components: schemas: Contract: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ customerId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: The customer the contract bills. name: anyOf: - type: string - type: 'null' description: >- The contract's name, such as the agreement's title; null when it has none. It is not printed on invoices. currencyCode: type: string enum: - USD - CAD - EUR - USDC description: The currency the contract bills in. startAt: anyOf: - type: string - type: 'null' format: date-time description: >- The calendar date the contract starts, carried at UTC midnight. The time is not data. endAt: anyOf: - type: string - type: 'null' format: date-time description: >- The calendar date the contract ends, carried at UTC midnight: it covers the days before this date, not the date itself. It includes changes that are finalized but have not taken effect yet, and any agreed cancellation. The time is not data. cancelsAt: anyOf: - type: string - type: 'null' format: date-time description: >- The calendar date an agreed cancellation ends the contract, carried at UTC midnight; null when no cancellation has been agreed. It is also endAt. The time is not data. paymentTermsDays: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- How many days the customer has to pay an invoice once it is issued, under the current amendment. lifecycleStatus: type: string enum: - DRAFT - ACTIVE - EXPIRED - CANCELLED - DELETED description: >- DRAFT: the contract's terms have not been agreed yet. ACTIVE: the terms are agreed and the contract has not ended, including one that has not started yet. EXPIRED: the contract has ended. CANCELLED: the contract was ended by a cancellation. DELETED: the contract was deleted; a list includes it only when lifecycleStatuses names DELETED. autoIssue: type: boolean description: >- Whether the contract's invoices are issued on their periodStartAt without a person approving them. An invoice issued this way is not emailed to the customer. This does not apply while the entity is in billing setup, to an invoice whose period starts on or before the day billing setup finished, or to an invoice a person was asked to review. processingInvoices: type: boolean description: >- Whether the contract's invoices are still being updated after a change to its terms or its deletion. processingInvoicesStartedAt: anyOf: - type: string - type: 'null' description: >- When the change that processingInvoices is waiting on was last requested; null while processingInvoices is false. autoRenew: type: boolean description: >- Whether the contract renews itself. A renewal is a new contract on the same terms that starts when this one ends. When true, the renewal is created on autoRenewalAt, so none while that is null, and is agreed automatically once this contract's terms are finalized. A contract already past its end when its terms are written or finalized gets one renewal for each term since. A change to this contract made after its renewal is agreed goes to a person to agree. When false, nothing is created automatically; from autoRenewalAt a person is asked to decide. notes: anyOf: - type: string - type: 'null' description: >- A note for the entity's own staff. It is never printed on an invoice. autoRenewalAt: anyOf: - type: string - type: 'null' format: date-time description: >- The calendar date the contract comes up for renewal, carried at UTC midnight: renewalNoticeDays before the current amendment ends; null when renewalNoticeDays is null. Only a running contract with finalized terms, no agreed cancellation and no renewal comes up for renewal. The time is not data. renewalNoticeDays: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- How many days before the current amendment ends the contract comes up for renewal; null when it never does, so nothing is created or asked before it ends, even when autoRenew is true. renewingContractId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' description: The contract this one renews; null when it is not a renewal. renewalContractId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' description: >- The contract that renews this one, a draft renewal included and a deleted one not; null when there is none. currentAmendmentId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' description: >- The amendment whose terms apply today: the latest finalized one that has started, or amendment 0 until one has. currentAmendmentStatus: anyOf: - type: string enum: - DRAFT - FINALIZING - FINALIZED - VOIDING - VOIDED - type: 'null' description: >- The status of the current amendment. DRAFT means the contract's terms have not been agreed yet. currentAmendmentStartAt: anyOf: - type: string - type: 'null' format: date-time description: >- The calendar date the current amendment takes or took effect, carried at UTC midnight. The time is not data. draftAmendmentId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' description: >- The amendment being written and not yet agreed; null when there is none. It is the same as currentAmendmentId while the contract's terms have never been agreed. futureAmendment: anyOf: - $ref: '#/components/schemas/Amendment' - type: 'null' description: >- Agreed changes to the contract that have not taken effect yet; null when there are none. Once it has started and is finalized, it becomes the current amendment. A scheduled cancellation shows in cancelsAt instead. subscriptionBillableCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: How many SUBSCRIPTION billables the current amendment carries. oneTimeBillableCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: How many ONE_TIME billables the current amendment carries. contractHealth: type: string enum: - RENEWAL_DUE - ENDING - HEALTHY - UPCOMING - NO_ACTIVE_CONTRACT - DRAFT_ONLY description: >- Whether the contract needs attention. RENEWAL_DUE: it has come up for renewal, does not renew itself and no agreed contract of the customer follows it yet, so a person needs to decide. ENDING: its current amendment ends within 30 days, and it does not renew itself, never comes up for renewal and has no cancellation agreed. HEALTHY: running and needs nothing. UPCOMING: agreed and not started yet. NO_ACTIVE_CONTRACT: expired, ended by a cancellation, or deleted. DRAFT_ONLY: its terms have not been agreed yet. createdAt: type: string updatedAt: type: string required: - id - customerId - name - currencyCode - startAt - endAt - cancelsAt - paymentTermsDays - lifecycleStatus - autoIssue - processingInvoices - processingInvoicesStartedAt - autoRenew - notes - autoRenewalAt - renewalNoticeDays - renewingContractId - renewalContractId - currentAmendmentId - currentAmendmentStatus - currentAmendmentStartAt - draftAmendmentId - futureAmendment - subscriptionBillableCount - oneTimeBillableCount - contractHealth - createdAt - updatedAt additionalProperties: false description: >- An agreement between the entity and one of its customers. It sets what the customer is billed for, from when and until when, and whether the agreement renews when it ends. error.BAD_REQUEST: type: object properties: message: type: string description: The error message example: Input validation failed code: type: string description: The error code example: BAD_REQUEST issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Input validation failed error (400) description: The error information example: code: BAD_REQUEST message: Input validation failed issues: [] error.UNAUTHORIZED: type: object properties: message: type: string description: The error message example: Unauthorized code: type: string description: The error code example: UNAUTHORIZED issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Unauthorized error (401) description: The error information example: code: UNAUTHORIZED message: Unauthorized issues: [] error.INTERNAL_SERVER_ERROR: type: object properties: message: type: string description: The error message example: An unexpected error occurred. code: type: string description: The error code example: INTERNAL_SERVER_ERROR issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: An unexpected error occurred. error (500) description: The error information example: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred. issues: [] Amendment: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ contractId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ amendmentNumber: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- The amendment's place among the contract's amendments: 0 for the original terms, higher for each later one. status: type: string enum: - DRAFT - FINALIZING - FINALIZED - VOIDING - VOIDED description: >- DRAFT: being written; only a draft's terms can change. FINALIZING: agreed, and the contract's invoices are being updated to match. FINALIZED: agreed, and the invoices match. VOIDING: being withdrawn, and the invoices are being updated back to the terms before it. VOIDED: withdrawn; it no longer applies. type: type: string enum: - MODIFICATION - CANCELLATION description: >- MODIFICATION: changes the contract's terms from startAt. CANCELLATION: ends the contract on endAt. processingInvoices: type: boolean description: >- Whether the contract's invoices are still being updated after this amendment was finalized or voided, or the contract was deleted. startAt: format: date-time description: >- The calendar date these terms take effect, carried at UTC midnight. The time is not data. type: string endAt: format: date-time description: >- The calendar date these terms end, carried at UTC midnight: they cover the days before this date, not the date itself. The time is not data. type: string paymentTermsDays: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- How many days the customer has to pay an invoice billed under these terms once it is issued. finalizedAt: anyOf: - type: string - type: 'null' description: >- When the amendment became FINALIZED; null if it has not. It stays set if the amendment is voided later. voidedAt: anyOf: - type: string - type: 'null' description: >- When someone last asked to withdraw the amendment, which made it VOIDING; null if nobody has. createdAt: type: string updatedAt: type: string required: - id - contractId - amendmentNumber - status - type - processingInvoices - startAt - endAt - paymentTermsDays - finalizedAt - voidedAt - createdAt - updatedAt additionalProperties: false description: >- A change to a contract's terms from its startAt. It holds every term from that date, not only the ones that change. Amendment 0 holds the terms the contract was created with. securitySchemes: BearerAuth: type: http scheme: bearer description: 'An API key created in Settings, sent as `Authorization: Bearer `.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.