> ## Documentation Index > Fetch the complete documentation index at: https://sendcloud.dev/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a list of contracts > Retrieve the list of contracts you have in your Sendcloud account. It will also return the `id` of each contract, which you can use to retrieve information about a specific contract. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. ## OpenAPI ````yaml /.openapi/v3/contracts/openapi.yaml get /contracts openapi: 3.1.0 info: title: Contracts API version: 3.0.0 description: >- The Contracts API allows you to manage and retrieve information about your direct shipping contracts connected to your Sendcloud account. contact: name: Sendcloud API Support email: contact@sendcloud.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://panel.sendcloud.sc/api/v3 description: Sendcloud Production security: [] tags: - name: Contracts paths: /contracts: get: tags: - Contracts summary: Retrieve a list of contracts description: >- Retrieve the list of contracts you have in your Sendcloud account. It will also return the `id` of each contract, which you can use to retrieve information about a specific contract. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. operationId: sc-public-v3-scp-get-all_contracts parameters: - schema: type: string in: query name: carrier_code description: >- The carrier you want to filter for, for instance: postnl. You can find available carriers in your Sendcloud account settings. required: false - schema: type: boolean in: query name: is_active description: Filter contracts based on the status. - schema: type: string in: query name: client_id description: Filter direct contracts based on the client id. - schema: type: string in: query name: name description: >- Filter direct contracts based on the contract's name. Will search for a case-sensitive exact match. - schema: type: string in: query name: country_code description: >- Filter contracts based on the country of the contract, it should be in the ISO 3166-1 alpha-2 format. example: NL - $ref: '#/components/parameters/Cursor' - schema: type: integer in: query name: page_size description: The size of the page to fetch example: 100 responses: '200': description: OK content: application/json: schema: description: Retrieve contracts type: object properties: data: type: array items: $ref: '#/components/schemas/contract' required: - data examples: RetrieveContracts: summary: Retrieve a list of contracts value: data: - id: 60 carrier: code: lettresuivie name: Lettre Suivie client_id: sendcloud-1 country: FR is_default_per_carrier: true state: active type: direct - id: 61 carrier: code: poste_italiane name: Poste Italiane client_id: sendcloud-1 country: IT is_default_per_carrier: true state: active type: direct headers: Link: description: >- The pagination links, according to the web linking specification (RFC8288). schema: type: string example: >- ; rel="prev", ; rel="next" '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/errors' examples: BadRequest: summary: Bad Request value: errors: - detail: Value error, Carrier x does not exist. status: '400' code: validation_error source: parameter: query carrier '429': description: Throttled security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] components: parameters: Cursor: in: query name: cursor description: >- The cursor query string is used as the pivot value to filter results. If no value is provided, the first page of results will be returned. To get this value, you must encode the offset, reverse and position into a base64 string. There are 3 possible parameters to encode: - `o`: Offset - `r`: Reverse - `p`: Position For example, `r=1&p=300` encoded as a base64 string would be `cj0xJnA9MzAw`. The query string would then be `cursor=cj0xJnA9MzAw`. schema: type: string example: cj0xJnA9MzAw schemas: contract: title: Contract description: User contract type: object properties: id: type: integer format: int64 minimum: 1 description: Unique identifier of the contract. client_id: description: >- Value of the carrier specific key for contact (e.g. the value of DelisID in DPD Benelux, username for DHL Express). type: - string - 'null' carrier: type: object properties: code: type: string name: type: string minLength: 1 description: Carrier name. name: type: string description: >- A custom name set by the user used to identify this contract throughout the platform. maxLength: 50 country_code: type: string description: The country of the contract, as an ISO 3166-1 alpha-2. example: NL is_default_per_carrier: type: boolean description: >- Indicates if the contract is marked as default. When you have multiple active direct contracts for the same carrier, default indicates that the contract will be prioritized over the other direct contracts for the same carrier, when no contract is explicitly mentioned while creating a parcel. You can have only one default direct contract per carrier and it will always be False for the broker and subbroker. The default can be configured in the "My contracts" page in the Sendcloud platform. state: type: string description: State of the contract enum: - active - inactive - validating - validation_failed example: active type: type: string description: Contract type enum: - direct - broker - subbroker example: direct error: type: - string - 'null' description: An error message when validating contract example: Missing or invalid shipper number errors: title: Errors type: object description: A standardized format for errors in JSON:API responses. properties: errors: type: - array - object items: type: object allOf: - $ref: '#/components/schemas/ErrorObject' required: - status - code - detail ErrorObject: title: Error type: object description: Error in a JSON:API error format properties: id: type: string description: A unique identifier for the error. links: type: object description: >- A set of hyperlinks that provide additional information about the error. properties: about: type: string description: A URL that provides additional information about the error. status: type: string format: int32 description: The HTTP status code of the error. minLength: 1 code: type: string description: A unique error code for the error, in snake case format. minLength: 1 enum: - unknown_field - invalid - forbidden - invalid_choice - min_value - 'null' - not_found - required - not_a_list - non_field_errors - authentication_failed - validation_error - parcel_announcement_error title: type: string description: A short, human-readable summary of the error. minLength: 1 detail: type: string description: A human-readable explanation of the error. minLength: 1 source: type: object description: >- An object that identifies the source of the error within the request payload. properties: pointer: type: string description: >- A `JSON` pointer to the location of the error within the request payload. parameter: type: string description: The name of the `query` parameter that caused the error. header: type: string description: The name of the `header` parameter that caused the error. meta: type: object description: Additional metadata about the error. securitySchemes: HTTPBasicAuth: type: http description: >- Basic Authentication using API key and secrets is currently the main authentication mechanism. scheme: basic OAuth2ClientCreds: type: oauth2 description: >- OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources. flows: clientCredentials: tokenUrl: https://account.sendcloud.com/oauth2/token/ scopes: api: Default OAuth scope required to access Sendcloud API. ````