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

# List contracts

> This endpoint allows fetching a list of contracts along with the plan instances attached to each one. Filter by customer to reach the plan instances of a given customer.



## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/contracts/
openapi: 3.1.0
info:
  title: API Reference
  version: '1.0'
  description: Aira API Reference
  x-logo:
    url: https://static.useaira.com/images/airalogo.svg
    backgroundColor: '#FFFFFF'
    altText: Aira Logo
servers:
  - url: https://api.useaira.com
    description: API base URL
security:
  - ApiKey: []
paths:
  /v1/contracts/:
    get:
      tags:
        - Contracts
      summary: List contracts
      description: >-
        This endpoint allows fetching a list of contracts along with the plan
        instances attached to each one. Filter by customer to reach the plan
        instances of a given customer.
      parameters:
        - schema:
            type: array
            items:
              type: string
              format: uuid
          in: query
          name: customerIds[]
          required: false
          description: >-
            Only return contracts of these customers, identified by their id in
            our system.
        - schema:
            type: array
            items:
              type: string
              pattern: ^[a-zA-Z0-9_-]+$
          in: query
          name: customerExternalIds[]
          required: false
          description: >-
            Only return contracts of these customers, identified by their id in
            your system.
        - schema:
            type: array
            items:
              type: string
              enum:
                - active
                - canceled
                - completed
                - draft
          in: query
          name: status[]
          required: false
          description: >-
            Only return contracts in these statuses. All statuses are returned
            when omitted.
        - schema:
            type: number
            default: 0
            minimum: 0
          in: query
          name: offset
          required: false
          description: Number of items to skip before collecting the page.
        - schema:
            type: number
            minimum: 1
            default: 100
            maximum: 100
          in: query
          name: limit
          required: true
          description: Maximum number of items to return per page.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      description: >-
                        Schema representing a contract and the plan instances
                        attached to it.
                      properties:
                        id:
                          description: The unique identifier of the contract in our system.
                          type: string
                          format: uuid
                        startDate:
                          description: The start date of the contract.
                          type: string
                          format: date
                        endDate:
                          description: >-
                            The end date of the contract. Null if the contract
                            has no end date.
                          type:
                            - 'null'
                            - string
                          format: date
                        status:
                          description: The current status of the contract.
                          type: string
                          enum:
                            - active
                            - canceled
                            - completed
                            - draft
                        customFields:
                          type: object
                          description: >-
                            Custom fields that can be associated with the
                            entity. The fields must be previously created in the
                            system before they can be used.
                          additionalProperties:
                            anyOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                          default: {}
                          example:
                            customField1: value1
                            customField2:
                              - value2
                              - value3
                        planInstances:
                          description: >-
                            The plan instances attached to the contract. While
                            the contract is draft or active only its active plan
                            instances are listed; once the contract is completed
                            or canceled, all of them are.
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                description: >-
                                  The unique identifier of the plan instance in
                                  our system. Use it to fetch or update the plan
                                  instance.
                                type: string
                                format: uuid
                              planId:
                                description: >-
                                  The unique identifier of the plan this
                                  instance was created from.
                                type: string
                                format: uuid
                              name:
                                description: >-
                                  The name of the plan this instance was created
                                  from.
                                type: string
                              status:
                                description: The current status of the plan instance.
                                type: string
                                enum:
                                  - active
                                  - canceled
                                  - completed
                            required:
                              - id
                              - planId
                              - name
                              - status
                            additionalProperties: false
                      required:
                        - id
                        - startDate
                        - endDate
                        - status
                        - customFields
                        - planInstances
                      additionalProperties: false
                    description: A list of items.
                  hasMore:
                    description: Indicates if there are more items to fetch.
                    type: boolean
                required:
                  - items
                  - hasMore
                additionalProperties: false
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      description: API Key Authentication.
      name: X-API-KEY
      in: header

````