Cint Exclusive Endpoints API

openapi: 3.2.0
info:
  title: Demand Exclusive Endpoints API
  description: Cint's demand ordering API is REST oriented.
  version: '2025-12-18'
servers:
- description: Production server
  url: https://api.cint.com/v1
security:
- BearerAuth: []
tags:
- name: Exclusive Endpoints
  description: For more information, if you need functionality in this section, please contact your account manager
paths:
  /demand/accounts/{account_id}/business-units/{business_unit_id}/generate-price-prediction:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    post:
      operationId: generate_price_prediction
      summary: Generates a price prediction
      description: 'Predicts the cost per interview (CPI) for a potential target group using either a `rate_card` or `dynamic` pricing model. The model you choose must match the business unit''s pricing configuration.

        Private Exchange required.

        This endpoint is only available for accounts with a Private Exchange. If your account does not have this feature enabled, requests will fail with a 403 Forbiddenerror. Please contact your account manager if you need access to this functionality.'
      tags:
      - Exclusive Endpoints
      parameters:
      - $ref: '#/components/parameters/AccountID'
      - $ref: '#/components/parameters/BusinessUnitID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRedactedPricePredictionRequest'
            examples:
              rate_card:
                summary: Rate Card Prediction
                description: Request a price prediction using the rate card pricing model
                value:
                  config:
                    type: rate_card
                    country_code: US
                    expected_incidence_rate: 0.25
                    expected_length_of_interview_minutes: 15
                    maximum_cpi:
                      value: '10.00'
                      currency_code: USD
              dynamic:
                summary: Dynamic Pricing Prediction
                description: Request a price prediction using the dynamic pricing model
                value:
                  config:
                    type: dynamic
                    user_requested_cpi:
                      value: '5.50'
                      currency_code: USD
      responses:
        '200':
          description: The price prediction was generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRedactedPricePredictionResponse'
              example:
                buyer_account_id: 101
                buyer_business_unit_id: '1234'
                buyer_business_unit_exchange_rate_from_usd: 1.0
                open_exchange_price:
                  pricing_context:
                    type: rate_card
                    rate_card_token: some_rate_card_token
                  cost_per_interview:
                    value: '4.75'
                    currency_code: USD
                    currency_scale: 2
                private_exchange_prices:
                - supplier_id: '43'
                  pricing_context:
                    type: dynamic
                  cost_per_interview:
                    value: '5.50'
                    currency_code": USD
                    currency_scale: 2
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /demand/accounts/{account_id}/business-units/{business_unit_id}/target-groups/{target_group_id}/price:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/BusinessUnitID'
    - $ref: '#/components/parameters/TargetGroupID'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      operationId: get_target_group_price
      summary: Retrieves the pricing details for a target group
      description: 'Retrieves the current pricing details for a specific target group. The response includes the cost per interview (CPI) and the pricing context (`rate_card` or `dynamic`) for both the Open Exchange and any applicable Private Exchange suppliers.

        Private Exchange required.

        This endpoint is only available for accounts with a Private Exchange. If your account does not have this feature enabled, requests will fail with a `403 Forbidden` error. Please contact your account manager if you need access to this functionality.'
      tags:
      - Exclusive Endpoints
      responses:
        '200':
          description: The pricing details for the target group were retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTargetGroupPriceResponse'
              example:
                price_type: specification
                buyer_account_id: 101
                buyer_business_unit_id: '1234'
                target_group_id: 01BTGNYV6HRNK8K8VKZASZCFP1
                buyer_business_unit_exchange_rate_from_usd: 1.0
                pricing_config_token: MDFKSE42MDQ1RFg2Tk0wQjlBQ0Q5QVhQQzk7Nw==
                open_exchange_price:
                  pricing_context:
                    type: rate_card
                    rate_card_token: some_rate_card_token
                  cost_per_interview:
                    value: '4.75'
                    currency_code: USD
                    currency_scale: 2
                private_exchange_prices:
                - supplier_id: '43'
                  pricing_context:
                    type: dynamic
                  cost_per_interview:
                    value: '5.50'
                    currency_code: USD
                    currency_scale: 2
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '500':
          $ref: '#/components/responses/Error_Internal'
components:
  schemas:
    CurrencyCode:
      type: string
      description: The three-letter ISO 4217 currency code, in uppercase. The code must correspond to a currency supported by Cint Exchange.
      example: USD
    AccountID:
      description: The account's unique identifier.
      type: integer
      format: int32
      example: 101
    PrivateExchangePricePrediction:
      type: object
      description: Contains the predicted pricing details for a single Private Exchange supplier.
      required:
      - pricing_context
      - supplier_id
      - cost_per_interview
      properties:
        pricing_context:
          description: The pricing context used in the calculation. The `type` field within the object indicates the model (`rate_card` or `dynamic`).
          oneOf:
          - $ref: '#/components/schemas/DynamicPricingContext'
          - $ref: '#/components/schemas/RateCardPricingContext'
        supplier_id:
          type: string
          description: The supplier ID of the private exchange supplier.
          example: '3214'
        cost_per_interview:
          $ref: '#/components/schemas/MonetaryAmount'
    RateCardToken:
      type: string
      description: An opaque token that uniquely identifies the rate card configuration used in a pricing calculation.
      example: MDFKSE42MDQ1RFg2Tk0wQjlBQ0Q5QVhQQzk7Nw==
    DynamicPricingPredictionConfig:
      title: Dynamic pricing configuration
      type: object
      description: Configuration used for dynamic pricing, specifying the user-requested cost per interview.
      required:
      - type
      - user_requested_cpi
      properties:
        type:
          type: string
          enum:
          - dynamic
          description: The pricing model. For this configuration, the value is always 'dynamic'. (And 'rate_card' respectively).
        user_requested_cpi:
          allOf:
          - $ref: '#/components/schemas/MonetaryAmountRequestModel'
          description: The requested CPI chosen by the user.
    GetRedactedPricePredictionResponse:
      type: object
      description: A price prediction containing the estimated cost per interview (CPI) for the Open Exchange and applicable Private Exchanges.
      required:
      - buyer_account_id
      - buyer_business_unit_id
      - buyer_business_unit_exchange_rate_from_usd
      - open_exchange_price
      - private_exchange_prices
      properties:
        buyer_account_id:
          $ref: '#/components/schemas/AccountID'
        buyer_business_unit_id:
          $ref: '#/components/schemas/BusinessUnitID'
        buyer_business_unit_exchange_rate_from_usd:
          type: number
          format: float
          description: The live exchange rate towards USD.
        open_exchange_price:
          allOf:
          - $ref: '#/components/schemas/OpenExchangePricePrediction'
        private_exchange_prices:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/PrivateExchangePricePrediction'
    OpenExchangePricePrediction:
      type: object
      description: Contains the predicted pricing details for the Cint Exchange.
      required:
      - pricing_context
      - cost_per_interview
      properties:
        pricing_context:
          description: The pricing context used in the calculation. The `type` field within the object indicates the model (`rate_card` or `dynamic`).
          oneOf:
          - $ref: '#/components/schemas/DynamicPricingContext'
          - $ref: '#/components/schemas/RateCardPricingContext'
        cost_per_interview:
          $ref: '#/components/schemas/MonetaryAmount'
    GetTargetGroupPriceResponse:
      type: object
      description: The pricing details for a target group, including the pricing context (e.g., dynamic or rate card) and cost per interview (CPI).
      required:
      - price_type
      - buyer_account_id
      - buyer_business_unit_id
      - target_group_id
      - buyer_business_unit_exchange_rate_from_usd
      - open_exchange_price
      - private_exchange_prices
      - pricing_config_token
      properties:
        price_type:
          type: string
          enum:
          - specification
          - prediction
          description: Indicates whether the price is a specification or a prediction.
        buyer_account_id:
          $ref: '#/components/schemas/AccountID'
        buyer_business_unit_id:
          $ref: '#/components/schemas/BusinessUnitID'
        target_group_id:
          $ref: '#/components/schemas/TargetGroupID'
        buyer_business_unit_exchange_rate_from_usd:
          type: number
          format: float
          description: The exchange rate from the buyer's business unit currency to USD at the time the target group was launched.
        pricing_config_token:
          $ref: '#/components/schemas/PricingConfigToken'
        open_exchange_price:
          type: object
          description: The pricing context and cost per interview for the Cint Open Exchange.
          required:
          - pricing_context
          - cost_per_interview
          properties:
            pricing_context:
              oneOf:
              - $ref: '#/components/schemas/DynamicPricingContext'
              - $ref: '#/components/schemas/RateCardPricingContext'
            cost_per_interview:
              $ref: '#/components/schemas/MonetaryAmount'
        private_exchange_prices:
          type: array
          description: Pricing details for each applicable Private Exchange supplier.
          items:
            type: object
            required:
            - supplier_id
            - pricing_context
            - cost_per_interview
            properties:
              pricing_context:
                oneOf:
                - $ref: '#/components/schemas/DynamicPricingContext'
                - $ref: '#/components/schemas/RateCardPricingContext'
              supplier_id:
                type: string
                example: '43'
              cost_per_interview:
                $ref: '#/components/schemas/MonetaryAmount'
    DynamicPricingContext:
      type: object
      description: The pricing context when a dynamic model is used.
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - dynamic
          description: The pricing model. For this context, the value is always 'dynamic'.
    BusinessUnitID:
      type: string
      description: The unique ID of the business unit, which determines the currency used for the target group.
      example: '1234'
    RateCardPricingContext:
      type: object
      description: The pricing context when a rate card model is used.
      required:
      - type
      - rate_card_token
      properties:
        type:
          type: string
          enum:
          - rate_card
          description: The pricing model. For this context, the value is always 'rate_card'.
        maximum_cpi:
          $ref: '#/components/schemas/MonetaryAmount'
          description: The maximum cost per interview (CPI) allowed for this pricing context.
        cpi_boost:
          $ref: '#/components/schemas/MonetaryAmount'
          description: An additional amount added to the calculated rate card CPI. The final CPI will not exceed the `maximum_cpi`.
        rate_card_token:
          $ref: '#/components/schemas/RateCardToken'
    PricingConfigToken:
      type: string
      description: A unique token representing an immutable pricing configuration.
      example: MDFKSE42MDQ1RFg2Tk0wQjlBQ0Q5QVhQQzk7Nw==
    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
          - 'null'
          description: An optional field containing a list of invalid parameters may be presented in validation errors for additional information.
          items:
            $ref: '#/components/schemas/InvalidParam'
    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
    TargetGroupID:
      description: A unique identifier for the target group, in ULID format.
      type: string
      pattern: ^[0-9A-Z]{26}$
      example: 01BTGNYV6HRNK8K8VKZASZCFP1
    MonetaryAmount:
      type: object
      description: Represents a monetary value, including the amount and its currency.
      properties:
        value:
          type: string
          description: A decimal encapsulated in a string representing the value in the denomination indicated by the code.
          example: '2.7352'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        currency_scale:
          allOf:
          - {}
          - type: integer
            description: The number of digits after the decimal separator, as defined by ISO 4217.
            example: 2
    MonetaryAmountRequestModel:
      type: object
      description: Represents a monetary value, including the amount and its currency.
      properties:
        value:
          type: string
          description: The monetary value, represented as a string to maintain precision.
          example: '2.7352'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
    RateCardPredictionConfig:
      title: Rate card pricing configuration
      type: object
      description: Configuration used for rate card pricing.
      required:
      - type
      - country_code
      - expected_incidence_rate
      - expected_length_of_interview_minutes
      properties:
        type:
          type: string
          enum:
          - rate_card
          description: Descriptor of the pricing model type.
        maximum_cpi:
          allOf:
          - $ref: '#/components/schemas/MonetaryAmountRequestModel'
          description: The maximum cost per interview (CPI) that can be set for the target group.
        cpi_boost:
          allOf:
          - $ref: '#/components/schemas/MonetaryAmountRequestModel'
          description: An additional amount added on top of the CPI calculated from the rate card. The final CPI will not exceed the `maximum_cpi`.
        country_code:
          type: string
          description: The two-letter country code, adhering to ISO 3166-1 alpha-2.
          example: US
        expected_length_of_interview_minutes:
          type: integer
          format: int32
          description: The expected median length of interview, in minutes.
          minimum: 1
          maximum: 45
          example: 1
        expected_incidence_rate:
          type: number
          format: float
          description: The expected incidence rate (IR) of the target audience, expressed as a decimal (e.g., 0.25 for 25%).
          minimum: 0
          maximum: 1
          multipleOf: 0.01
          example: 0.05
    GetRedactedPricePredictionRequest:
      type: object
      description: The request body for generating a price prediction.
      required:
      - config
      properties:
        config:
          description: The pricing configuration. The `type` field within the object determines which model to use (`rate_card` or `dynamic`).
          oneOf:
          - $ref: '#/components/schemas/RateCardPredictionConfig'
          - $ref: '#/components/schemas/DynamicPricingPredictionConfig'
  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_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.
    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_NotFound:
      description: A requested resource isn't found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            id: 7a5972ba-0825-4360-b852-fa2430e47034
            object: not_found_error
            detail: resource not found
    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
  parameters:
    BusinessUnitID:
      in: path
      name: business_unit_id
      schema:
        $ref: '#/components/schemas/BusinessUnitID'
      required: true
      description: The unique identifier for the business unit.
    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`.

        '
    AccountID:
      name: account_id
      description: The account's unique identifier.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/AccountID'
    TargetGroupID:
      name: target_group_id
      description: A unique identifier for the target group, in ULID format.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/TargetGroupID'
  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