> ## Documentation Index
> Fetch the complete documentation index at: https://alpha.developer.tomorro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List contracts

> Returns a paginated list of contracts in your organization. Supports cursor-based pagination, sorting, filtering, and optional text search on contract and counterparty names.



## OpenAPI

````yaml /openapi-2025-01-15.init.json get /contracts
openapi: 3.0.0
info:
  title: Tomorro API
  description: >
    The Tomorro Public API enables you to programmatically manage contracts,
    members, and counterparties. Build powerful integrations that automate your
    contract management workflows.


    ## API Version: 2025-01-15.init


    This documentation is for API version `2025-01-15.init`.


    > **Warning:** This version is deprecated. This version is deprecated.
    Please upgrade to 2025-01-29.alpha.


    ### Using this version

    ```

    curl -X GET https://api.tomorro.com/members \
      -H "x-api-key: YOUR_API_KEY" \
      -H "tomorro-version: 2025-01-15.init"
    ```
  version: 2025-01-15.init
  contact: {}
servers:
  - url: https://api.tomorro.com/v2
    description: Production
  - url: https://api.demo.tomorro.com/v2
    description: Demo
  - url: http://localhost:3015
    description: Local Development
security: []
tags: []
paths:
  /contracts:
    get:
      tags:
        - Contracts
      summary: List contracts
      description: >-
        Returns a paginated list of contracts in your organization. Supports
        cursor-based pagination, sorting, filtering, and optional text search on
        contract and counterparty names.
      operationId: ContractController_listContracts
      parameters:
        - name: limit
          required: false
          in: query
          description: Number of items per page (1-50)
          schema:
            minimum: 1
            maximum: 50
            default: 20
            example: 20
            type: number
        - name: after
          required: false
          in: query
          description: >-
            Cursor for forward pagination. Use the `next_cursor` value from a
            previous response.
          schema:
            example: eyJpZCI6IjEyMyJ9
            type: string
        - name: before
          required: false
          in: query
          description: >-
            Cursor for backward pagination. Use the `prev_cursor` value from a
            previous response.
          schema:
            example: eyJpZCI6IjEwMCJ9
            type: string
        - name: sort
          required: false
          in: query
          description: >-
            Sort order. Comma-separated list of fields. Prefix with `-` for
            descending. Allowed fields: `id`, `name`, `status`, `createdAt`,
            `updatedAt`. Default: `-createdAt`
          schema:
            example: '-createdAt,name'
            type: string
        - name: search
          required: false
          in: query
          description: >-
            Substring match on contract name or counterparty (external company)
            name. Leading and trailing whitespace is ignored; empty values are
            treated as no search.
          schema:
            example: acme
            type: string
        - name: status
          required: false
          in: query
          description: >-
            Filter by contract status. Formats: `status=draft` (equality),
            `status=ne:negotiating` (not equals), `status=in:signing,signed` (in
            list)
          schema:
            example: draft
            type: string
        - name: authorId
          required: false
          in: query
          description: Filter by author member ID
          schema:
            example: '123'
            type: string
        - name: counterpartyId
          required: false
          in: query
          description: Filter by counterparty ID
          schema:
            example: '456'
            type: string
        - name: contractTypeId
          required: false
          in: query
          description: >-
            Filter by a single contract type ID (UUID). Multiple types are not
            supported with `in:uuid1,uuid2`—use one request per contract type
            and merge results client-side if needed.
          schema:
            example: 2742c6e3-c57f-4f6e-bd18-019a79522639
            type: string
        - name: referentId
          required: false
          in: query
          description: Filter by referent member ID
          schema:
            example: '202'
            type: string
        - name: supervisorId
          required: false
          in: query
          description: Filter by supervisor member ID
          schema:
            example: '303'
            type: string
        - name: folderId
          required: false
          in: query
          description: Filter by folder ID
          schema:
            example: '404'
            type: string
        - name: startAt
          required: false
          in: query
          description: >-
            Filter by start date. Formats: `startAt=2024-01-01` (equality),
            `startAt=gte:2024-01-01` (greater than or equal),
            `startAt=lte:2024-12-31` (less than or equal)
          schema:
            example: '2024-01-01'
            type: string
        - name: endAt
          required: false
          in: query
          description: >-
            Filter by end date. Formats: `endAt=2024-12-31` (equality),
            `endAt=gte:2024-01-01` (greater than or equal),
            `endAt=lte:2024-12-31` (less than or equal)
          schema:
            example: '2024-12-31'
            type: string
        - name: createdAt
          required: false
          in: query
          description: >-
            Filter by creation date. Formats: `createdAt=2024-01-01` (equality),
            `createdAt=gte:2024-01-01` (greater than or equal),
            `createdAt=lte:2024-12-31` (less than or equal)
          schema:
            example: '2024-01-01'
            type: string
      responses:
        '200':
          description: List of contracts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractListResponseDto'
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Insufficient permissions
        '429':
          description: Too Many Requests - Rate limit exceeded
      security:
        - X-API-KEY: []
components:
  schemas:
    ContractListResponseDto:
      type: object
      properties:
        contracts:
          description: An array of Contract objects.
          example:
            - id: 550e8400-e29b-41d4-a716-446655440000
              name: Service Agreement - Acme Corp
              status: draft
              templateId: 550e8400-e29b-41d4-a716-446655440003
              author:
                id: 550e8400-e29b-41d4-a716-446655440004
                email: john.doe@example.com
              contractType:
                id: 550e8400-e29b-41d4-a716-446655440002
                name: Service Agreement
              counterparty:
                id: 550e8400-e29b-41d4-a716-446655440001
                name: Acme Corporation
              fields:
                - attributeDefinitionId: 123e4567-e89b-12d3-a456-426614174000
                  name: Department
                  value: Legal
              contractMembers:
                - id: 550e8400-e29b-41d4-a716-446655440004
                  email: john.doe@example.com
              integration: null
              signatories:
                - id: 550e8400-e29b-41d4-a716-446655440005
                  name: John Doe
                  email: john.doe@example.com
                  type: member
              createdAt: '2024-01-15T10:30:00.000Z'
              updatedAt: '2024-02-20T14:45:00.000Z'
          type: array
          items:
            $ref: '#/components/schemas/ContractResponseDto'
        hasNext:
          type: boolean
          description: >-
            Whether there are more results available after this page. If `true`,
            you can use the `after` cursor to fetch the next page.
          example: true
        hasPrevious:
          type: boolean
          description: >-
            Whether there are results available before this page. If `true`, you
            can use the `before` cursor to fetch the previous page.
          example: false
      required:
        - contracts
        - hasNext
        - hasPrevious
    ContractResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the contract.
          example: ctr_550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: The name or title of the contract.
          example: Service Agreement - Acme Corp
        status:
          type: string
          description: |-
            The current status of the contract.

            - `draft`: The contract is being created or edited.
            - `negotiating`: The contract is being reviewed with counterparties.
            - `signing`: The contract is in the signature process.
            - `signed`: All parties have signed the contract.
            - `canceled`: The contract has been canceled.
          example: draft
        counterparty:
          description: The counterparty associated with this contract.
          nullable: true
          example:
            id: 550e8400-e29b-41d4-a716-446655440001
            name: Acme Corporation
          type: object
          allOf:
            - $ref: '#/components/schemas/ContractCounterpartyDto'
        contractType:
          description: The type of  the contract, it is composed of many templates.
          nullable: true
          example:
            id: 550e8400-e29b-41d4-a716-446655440002
            name: Service Agreement
          type: object
          allOf:
            - $ref: '#/components/schemas/ContractTypeDto'
        templateId:
          type: string
          description: The template used to create this contract.
          nullable: true
          example: 550e8400-e29b-41d4-a716-446655440003
        author:
          description: The member who created this contract.
          example:
            id: 550e8400-e29b-41d4-a716-446655440004
            email: john.doe@example.com
          allOf:
            - $ref: '#/components/schemas/ContractMemberDto'
        fields:
          description: The fields associated with this contract.
          example:
            - attributeDefinitionId: 123e4567-e89b-12d3-a456-426614174000
              name: Department
              value: John Doe
          type: array
          items:
            $ref: '#/components/schemas/ContractFieldsDto'
        signatories:
          description: The signatories associated with this contract.
          example:
            - id: sig_550e8400-e29b-41d4-a716-446655440005
              name: John Doe
              email: john.doe@example.com
              type: member
          type: array
          items:
            $ref: '#/components/schemas/ContractSignatoryDto'
        integration:
          description: >-
            The third-party system this contract is linked to, when it was
            created via an integration (currently Salesforce or HubSpot). The
            shape mirrors the `integration` payload accepted on `POST
            /contracts`, so you can use this to look up the originating record
            in your CRM. `null` when the contract has no external link or was
            created from the Tomorro web app.
          nullable: true
          example:
            type: salesforce
            externalId: sf-123456
            externalEntity: Opportunity
            externalUrl: https://my-crm.example.com/opportunities/sf-123456
          type: object
          allOf:
            - $ref: '#/components/schemas/ContractIntegrationDto'
        contractMembers:
          description: The list of participants with this contract.
          example:
            - id: 550e8400-e29b-41d4-a716-446655440004
              email: john.doe@example.com
          type: array
          items:
            $ref: '#/components/schemas/ContractMemberDto'
        createdAt:
          format: date-time
          type: string
          description: >-
            Time at which the contract was created. Formatted as an ISO 8601
            date-time string.
          example: '2024-01-15T10:30:00.000Z'
        updatedAt:
          format: date-time
          type: string
          description: >-
            Time at which the contract was last updated. Formatted as an ISO
            8601 date-time string.
          example: '2024-02-20T14:45:00.000Z'
      required:
        - id
        - name
        - status
        - counterparty
        - contractType
        - templateId
        - author
        - fields
        - signatories
        - integration
        - createdAt
        - updatedAt
    ContractCounterpartyDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the counterparty.
          example: cp_550e8400-e29b-41d4-a716-446655440001
        name:
          type: string
          description: The display name of the counterparty (company or individual name).
          example: Acme Corporation
      required:
        - id
        - name
    ContractTypeDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the contract type.
          example: type_550e8400-e29b-41d4-a716-446655440002
        name:
          type: string
          description: The name of the contract type.
          example: Service Agreement
          nullable: true
      required:
        - id
        - name
    ContractMemberDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the member.
          example: mem_550e8400-e29b-41d4-a716-446655440004
        email:
          type: string
          description: The email address of the member.
          example: john.doe@example.com
      required:
        - id
        - email
    ContractFieldsDto:
      type: object
      properties:
        attributeDefinitionId:
          type: string
          description: Unique identifier for the attribute definition.
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: The display name of the attribute definition.
          example: Department
        value:
          type: string
          description: The value of the attribute.
          example: Marketing
          nullable: true
      required:
        - attributeDefinitionId
        - name
        - value
    ContractSignatoryDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the signatory.
          example: sig_550e8400-e29b-41d4-a716-446655440005
        name:
          type: string
          description: The name of the signatory.
          example: John Doe
        email:
          type: string
          description: The email address of the signatory.
          example: john.doe@example.com
        type:
          type: string
          description: The type of the signatory.
          enum:
            - member
            - guest
            - external
          example: member
      required:
        - id
        - name
        - email
        - type
    ContractIntegrationDto:
      type: object
      properties:
        type:
          type: string
          description: >-
            The third-party system the contract is linked to. Currently one of
            `salesforce` or `hubspot`; new values may be added as Tomorro ships
            support for additional integrations.
          enum:
            - salesforce
            - hubspot
          example: salesforce
        externalId:
          type: string
          description: >-
            External identifier of the linked record in the third-party system
            (e.g. the Salesforce Opportunity ID).
          example: sf-123456
        externalEntity:
          type: string
          description: >-
            External entity type the contract is linked to (e.g. `Opportunity`
            for Salesforce, `Deal` for HubSpot).
          nullable: true
          example: Opportunity
        externalUrl:
          type: string
          description: >-
            Deep link to the linked record in the third-party system, when one
            is available.
          nullable: true
          example: https://my-crm.example.com/opportunities/sf-123456
      required:
        - type
        - externalId
        - externalEntity
        - externalUrl
  securitySchemes:
    X-API-KEY:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key for authentication. Get your key at
        https://app.tomorro.com/settings/integrations?integration=api-key

````