openapi: 3.0.3
info:
  title: Demand Accounts Definitions API
  description: 'Cint''s demand ordering API is REST oriented. It has predictable resource based URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Error responses are also JSON-encoded and follow a standard format, providing a unique error ID and detailed information about what went wrong.


    Authentication is handled via bearer tokens passed in the `Authorization` header. All requests must also include a `Cint-API-Version` header with a date in `YYYY-MM-DD` format to specify the desired API version. Depending on the version you use, endpoint behavior may differ as we improve our API with every version release.


    While many operations work on a single object per request, the demand ordering API also provides asynchronous batch endpoints for performing bulk updates efficiently on certain resources. For safety, `POST` requests support an `Idempotency-Key` header to allow for safe retries without accidentally performing the same operation twice.

    '
  version: '2025-12-18'
servers:
- description: Production server
  url: https://api.cint.com/v1
security:
- BearerAuth: []
tags:
- name: Definitions
  description: Platform-wide definitions endpoints.
paths:
  /accounts/{account_id}/business-units:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: Lists business units for an account
      operationId: get_business_units
      description: "Lists available account business units. Business unit definitions are supposed to help you organize surveys between different parts of your organization. They also determine the currency used by their assigned surveys. \n\n:::info\nTo get default business unit assigned to the user within the account then use /accounts/{account_id}/users/{user_id}/business-units API mentioned under Accounts section.\n:::\n"
      responses:
        '200':
          description: A list of business units was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  business_units:
                    type: array
                    description: A list of business units.
                    items:
                      $ref: '#/components/schemas/BusinessUnit'
              example:
                business_units:
                - id: 1234
                  name: Example EMEA
                  currency_code: EUR
                  pricing_models:
                  - rate_card
                  - dynamic
                - id: 5678
                  name: Example APAC
                  currency_code: JPY
                  pricing_models:
                  - rate_card
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /accounts/{account_id}/clients:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: Lists clients for an account
      operationId: get_clients
      description: Lists the clients that have been configured for the specified account.
      parameters:
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageNumber'
      responses:
        '200':
          description: A list of clients was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  clients:
                    type: array
                    description: A list of clients.
                    items:
                      $ref: '#/components/schemas/ClientListItem'
              example:
                clients:
                - id: 1234
                  name: Acme Inc
                - id: 5678
                  name: Global Research Partners
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /countries:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: Lists all countries
      operationId: get_countries
      description: Lists all available countries. Countries are used for target group filtering purposes. `0/NA` is a special country code that can be used for scenarios where a country is not applicable.
      responses:
        '200':
          description: A list of countries was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  countries:
                    type: array
                    description: A list of countries.
                    items:
                      $ref: '#/components/schemas/CountryListItem'
              example:
                countries:
                - id: 243
                  code: GB
                  name: United Kingdom
                - id: 244
                  code: US
                  name: United States
                - id: 116
                  code: JP
                  name: Japan
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /industries:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: Lists all industries
      operationId: get_industries
      description: Lists the available industries that you can associate with your target groups.
      responses:
        '200':
          description: A list of industries was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  industries:
                    type: array
                    description: A list of industries.
                    items:
                      $ref: '#/components/schemas/IndustryListItem'
              example:
                industries:
                - id: 19
                  code: politics
                  name: Politics
                - id: 20
                  code: economy
                  name: Economy
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /industry-lockouts:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: Lists all industry lockouts
      operationId: get_industry_lockouts
      description: Lists the available industry lockout options. You can apply an industry lockout to a target group to prevent respondents from participating if they have recently completed another target group in the same industry.
      responses:
        '200':
          description: A list of industry lockouts was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  industry_lockouts:
                    type: array
                    description: A list of industry lockouts.
                    items:
                      $ref: '#/components/schemas/IndustryLockoutItem'
              example:
                industry_lockouts:
                - id: 90
                  code: past_90_days
                  name: Past 90 Days / 3 Months
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /integration-use-cases:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: List all supported integration cases
      operationId: get_integration_use_cases
      description: Lists all supported integration use cases, which indicate the purpose for which an integration will be used.
      responses:
        '200':
          description: A list of integration use cases was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  integration_use_cases:
                    type: array
                    description: A list of integration use cases.
                    items:
                      $ref: '#/components/schemas/IntegrationUseCaseListItem'
                example:
                  integration_use_cases:
                  - id: manage_surveys
                    name: Manage target groups
                    description: Create, update, and retrieve target groups, allocations, groups, qualifications, and quotas.
                  - id: performance_reporting
                    name: Performance reporting
                    description: Monitor target group performance and do reconciliation.
                  - id: financial_reporting
                    name: Financial reporting
                    description: Generate cost summary reports for sets of target groups.
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /locales:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: Lists all locales
      operationId: get_locales
      description: Lists all available locales (a combination of country and language) that are well-supported on the platform. You can use this endpoint to discover which locales are recommended for the best performance and panelist availability. The output will include ISO 3166-1 alpha-2 country codes and associated ISO 639-2/T three-letter language codes. You will use this to form a valid locale string where you specify the three-letter language code, an underscore, and the two-letter country code e.g., eng_us. Use this locale when browsing profile library or creating a target group.
      responses:
        '200':
          description: A list of locales was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locales'
              example:
                locales:
                - country:
                    code: in
                    name: India
                  languages:
                  - is_preferred: true
                    name: English
                    code: eng
                  - is_preferred: true
                    name: Hindi
                    code: hin
                - country:
                    code: us
                    name: United States
                  languages:
                  - is_preferred: true
                    name: English
                    code: eng
                  - is_preferred: false
                    name: Spanish
                    code: spa
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /study-types:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: Lists study types
      operationId: get_study_types
      description: Lists the available study types. You can assign a study type to a target group to indicate its purpose and associated limits.
      responses:
        '200':
          description: A list of study types was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  study_types:
                    type: array
                    description: A list of study types.
                    items:
                      $ref: '#/components/schemas/StudyTypeListItem'
              example:
                study_types:
                - id: 1
                  code: adhoc
                  name: Adhoc
                - id: 2
                  code: diary
                  name: Diary
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /suppliers:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      tags:
      - Definitions
      summary: Lists suppliers
      operationId: get_suppliers
      description: Lists the suppliers available on the Cint Exchange. You can use the IDs retrieved from this endpoint to configure allocation templates.
      responses:
        '200':
          description: A list of suppliers was retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  suppliers:
                    type: array
                    description: A list of suppliers.
                    items:
                      $ref: '#/components/schemas/SupplierDetailsItem'
              example:
                suppliers:
                - id: 4351
                  code: ACE
                  name: Acme Inc
                - id: 3334
                  code: BCD
                  name: BCD Inc
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '500':
          $ref: '#/components/responses/Error_Internal'
components:
  schemas:
    CountryListItem:
      type: object
      description: Contains details for a single country.
      readOnly: true
      properties:
        id:
          type: integer
          description: Unique identifier of the country.
          example: 243
        code:
          type: string
          description: Unique text code of the country.
          example: GB
        name:
          type: string
          description: A human-readable name for the country.
          example: United Kingdom
    SupplierDetailsItem:
      type: object
      description: Contains details for a single supplier.
      readOnly: true
      properties:
        id:
          type: integer
          description: Unique identifier of the supplier.
          example: 4321
        code:
          type: string
          description: Unique text code of the supplier.
          example: ACE
        name:
          type: string
          description: A human-readable name for the supplier.
          example: Acme Inc
    InvalidParam:
      type: object
      description: Describes a single invalid parameter in a request.
      properties:
        name:
          type: string
          description: The name of the parameter that failed validation.
        reason:
          type: string
          description: A short explanation of why the parameter was invalid.
      required:
      - name
      - reason
    IndustryListItem:
      type: object
      description: Contains details for a single industry.
      readOnly: true
      properties:
        id:
          type: integer
          description: Unique identifier of the industry.
          example: 19
        code:
          type: string
          description: Unique text code of the industry.
          example: politics
        name:
          type: string
          description: A human-readable name for the industry.
          example: Politics
    StudyTypeListItem:
      type: object
      description: Contains details for a single study type.
      readOnly: true
      properties:
        id:
          type: integer
          description: Unique identifier of the study type.
          example: 1
        code:
          type: string
          description: Unique text code of the study type.
          example: adhoc
        name:
          type: string
          description: A human-readable name for the study type.
          example: Adhoc
    ClientListItem:
      type: object
      description: Contains details for a single client.
      readOnly: true
      properties:
        id:
          type: integer
          description: Unique identifier of the client.
          example: 1234
        name:
          type: string
          description: A human-readable name for the client.
          example: Acme Inc
    IndustryLockoutItem:
      type: object
      description: Contains details for a single industry lockout.
      readOnly: true
      properties:
        id:
          type: integer
          description: Unique identifier of the industry lockout.
          example: 90
        code:
          type: string
          description: Unique text code of the industry lockout.
          example: past_90_days
        name:
          type: string
          description: A human-readable name for the industry lockout.
          example: Past 90 Days / 3 Months
    Error:
      type: object
      description: The standard error object returned for all failed API requests.
      required:
      - object
      - detail
      properties:
        id:
          type: string
          format: uuid
          description: A unique identifier for this specific error instance.
        object:
          type: string
          description: A short informative string identifying the type of the error
          pattern: ^([a-z]*_)*([a-z]*)$
        detail:
          type: string
          description: An error message provides a concise overview of the cause of the error.
        invalid_params:
          type: array
          nullable: true
          description: An optional field containing a list of invalid parameters may be presented in validation errors for additional information.
          items:
            $ref: '#/components/schemas/InvalidParam'
    BusinessUnit:
      type: object
      description: Contains details for a single business unit.
      readOnly: true
      properties:
        id:
          type: integer
          description: Unique identifier of the business unit.
          example: 1234
        name:
          type: string
          description: A human-readable name for the business unit.
          example: Example
        currency_code:
          type: string
          description: The ISO 4217 currency code for the business unit.
          example: GBP
        pricing_models:
          type: array
          description: Contains available pricing models for the business unit.
          items:
            type: string
            description: The pricing model assigned to the business unit.
            enum:
            - rate_card
            - dynamic
            example: rate_card
    AccountID:
      description: The account's unique identifier.
      type: integer
      format: int32
      example: 101
    Locales:
      type: object
      description: Contains a list of suggested countries and their supported languages.
      properties:
        locales:
          type: array
          description: A list of suggested locales.
          items:
            type: object
            properties:
              country:
                type: object
                description: Contains details for a single country based on the locale.
                properties:
                  code:
                    type: string
                    description: The ISO 3166-1 alpha-2 country code.
                  name:
                    type: string
                    description: The name of the country.
              languages:
                type: array
                description: A list of supported country languages.
                items:
                  type: object
                  properties:
                    is_preferred:
                      type: boolean
                      description: Indicates whether the country language is preferred for the country.
                    name:
                      type: string
                      description: A human-readable name for the country language.
                    code:
                      type: string
                      description: The ISO 639-2 (3-letter) language code.
      example:
        locales:
        - country:
            code: in
            name: India
          languages:
          - is_preferred: true
            name: English
            code: eng
          - is_preferred: true
            name: Hindi
            code: hin
          - is_preferred: false
            name: Bengali
            code: ben
        - country:
            code: us
            name: United States
          languages:
          - is_preferred: true
            name: English
            code: eng
          - is_preferred: true
            name: Spanish
            code: spa
          - is_preferred: false
            name: Chinese Simplified
            code: chi
    IntegrationUseCaseListItem:
      type: object
      description: Contains details for a single integration use case.
      readOnly: true
      properties:
        id:
          type: string
          description: A unique identifier for the use case.
          example: manage_surveys
        name:
          type: string
          description: A name for the use case.
          example: Manage target groups
        description:
          type: string
          description: A description for the use case.
          example: Create, update, and retrieve surveys, allocations, groups, qualifications, and quotas.
  responses:
    Error_Internal:
      description: A request failed due to an internal error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            id: d94b8bb2-a540-4a91-9c05-2aa3ae9a5e1e
            object: unexpected_internal_error
            detail: an internal error has led to the failure of this operation
    Error_Forbidden:
      description: A requested is forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            id: fe68cdd2-ee87-4dbf-8950-63c5cbca94c7
            object: authorization_error
            detail: you don't have the right permissions to perform this operation
    Error_Unauthorized:
      description: A request is unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            id: 1dcf0f40-f0d1-4cf6-8c00-c3d019d32faf
            object: authorization_error
            detail: no valid authorization provided for this operation
    Error_BadRequest:
      description: A request is not valid and can't be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            id: 9e278238-d011-4e05-8327-1ce1d5d26254
            object: bad_request_error
            detail: Expected field 'foo' is missing.
  parameters:
    CintAPIVersion-2025-12-18:
      name: Cint-API-Version
      in: header
      required: true
      schema:
        type: string
        example: 2025-12-18
      description: 'This header is MANDATORY for all API requests. The API version format is `YYYY-MM-DD`.

        '
    PageSize:
      name: page_size
      in: query
      description: A limit on the number of objects to be returned, between 1 and 100.
      schema:
        type: integer
        default: 10
      example: 15
    PageNumber:
      name: page_number
      in: query
      description: The page number of the results to retrieve.
      schema:
        type: integer
        minimum: 0
        default: 0
      example: 2
    AccountID:
      name: account_id
      description: The account's unique identifier.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/AccountID'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token used for authentication and authorization. See [Authentication Process](https://developer.cint.com/en/guides#authentication-process) documentation for more information.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API Key Authentication