Cint Respondent Unique Codes API

openapi: 3.0.3
info:
  title: Demand Accounts Respondent Unique Codes 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: Respondent Unique Codes
  description: Allows you to insert respondent unique code(s) into the survey URL for each respondent entering the session.
paths:
  /demand/accounts/{account_id}/target-groups/{target_group_id}/respondent-unique-codes/live:
    post:
      operationId: upload_live_respondent_unique_codes
      summary: Upload live respondent unique codes
      description: "Uploads a batch of respondent unique codes for a target group. These codes are inserted into the **live URL** for each respondent who enters a survey session.\n\n:::note URL Setup Required\nBefore using this endpoint, you must set up your target group's live URL to include the `[%RESPONDENT_UNIQUE_CODE%]` placeholder.\n\n*Example live URL setup:*\n`https://example_live_url.com?id=[%RESPONDENT_UNIQUE_CODE%]`\n:::\n\n### Processing Rules\n\n*   **Batch Size**: You can submit a minimum of 1 and a maximum of 20,000 codes in a single request.\n*   **Code Format**: Codes must be between 1 and 128 characters and contain only alphanumeric characters, hyphens (`-`), and underscores (`_`). Leading and trailing whitespace will be removed.\n*   **Uniqueness**: Only unique codes are processed.\n    *   If you include duplicates within a single batch, only the first occurrence is considered.\n    *   If you upload codes that already exist for this target group's live URL, they will be ignored.\n\n:::caution Feature Access\nThis feature must be enabled for your account. If it's not enabled, this endpoint will return a `403 Forbidden` error. Please contact your account manager for more information.\n:::\n"
      parameters:
      - $ref: '#/components/parameters/AccountID'
      - $ref: '#/components/parameters/TargetGroupID'
      - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
      tags:
      - Respondent Unique Codes
      requestBody:
        description: The list of live respondent unique codes to upload.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadLiveRespondentUniqueCodesRequest'
            example:
              respondent_unique_codes:
              - abc-123-xyz-789
              - def-456-uvw-123
              - ghi-789-rst-456
      responses:
        '200':
          description: Returns a summary of the upload operation, including the number of new codes that were successfully added. Codes that were duplicates or already existed are ignored and not counted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadLiveRespondentUniqueCodesResponse'
              example:
                uploaded_count: 3
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '429':
          $ref: '#/components/responses/Error_RateLimit'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /demand/accounts/{account_id}/target-groups/{target_group_id}/respondent-unique-codes/live/stats:
    get:
      operationId: get_live_respondent_unique_codes_stats
      summary: Get live respondent unique code stats
      description: 'This endpoint returns a summary of the usage for live respondent unique codes for a specific target group. The response includes the total number of codes stored and the count of those that remain unconsumed.


        :::caution Feature Access

        This feature must be enabled for your account. If it''s not enabled, this endpoint will return a `403 Forbidden` error. Please contact your account manager for more information.

        :::

        '
      parameters:
      - $ref: '#/components/parameters/AccountID'
      - $ref: '#/components/parameters/TargetGroupID'
      - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
      tags:
      - Respondent Unique Codes
      responses:
        '200':
          description: Returns the total and unconsumed counts of live respondent unique codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLiveRespondentUniqueCodesStatsResponse'
              example:
                total_count: 1500
                unconsumed_count: 850
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '429':
          $ref: '#/components/responses/Error_RateLimit'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /demand/accounts/{account_id}/target-groups/{target_group_id}/respondent-unique-codes/live/unconsumed:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    delete:
      operationId: delete_unconsumed_live_respondent_unique_codes
      summary: Delete all unconsumed live respondent unique codes
      description: 'This endpoint permanently deletes all unconsumed **live** respondent unique codes for a specific target group.


        :::danger Destructive Action

        This action can potentially pause the target group if it''s currently live and runs out of codes. This operation cannot be undone.

        :::


        :::caution Feature Access

        This feature must be enabled for your account. If it''s not enabled, this endpoint will return a `403 Forbidden` error. Please contact your account manager for more information.

        :::

        '
      parameters:
      - $ref: '#/components/parameters/AccountID'
      - $ref: '#/components/parameters/TargetGroupID'
      tags:
      - Respondent Unique Codes
      responses:
        '204':
          description: Confirms that all unconsumed live respondent unique codes were deleted successfully.
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '429':
          $ref: '#/components/responses/Error_RateLimit'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /demand/accounts/{account_id}/target-groups/{target_group_id}/respondent-unique-codes/test:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    post:
      operationId: upload_test_respondent_unique_codes
      summary: Upload test respondent unique codes
      description: "Uploads a batch of respondent unique codes for a target group. These codes are inserted into the **test URL** for each respondent who enters a survey session for testing purposes.\n\n:::note URL Setup Required\nBefore using this endpoint, you must set up your target group's test URL to include the `[%RESPONDENT_UNIQUE_CODE%]` placeholder.\n\n*Example test URL setup:*\n`https://example_test_url.com?id=[%RESPONDENT_UNIQUE_CODE%]`\n:::\n\n### Processing Rules\n\n*   **Batch Size**: You can submit a minimum of 1 and a maximum of 20,000 codes in a single request.\n*   **Code Format**: Codes must be between 1 and 128 characters and contain only alphanumeric characters, hyphens (`-`), and underscores (`_`). Leading and trailing whitespace will be removed.\n*   **Uniqueness**: Only unique codes are processed.\n    *   If you include duplicates within a single batch, only the first occurrence is considered.\n    *   If you upload codes that already exist for this target group's test URL, they will be ignored.\n\n:::caution Feature Access\nThis feature must be enabled for your account. If it's not enabled, this endpoint will return a `403 Forbidden` error. Please contact your account manager for more information.\n:::\n"
      parameters:
      - $ref: '#/components/parameters/AccountID'
      - $ref: '#/components/parameters/TargetGroupID'
      tags:
      - Respondent Unique Codes
      requestBody:
        description: The request body for uploading test respondent unique codes.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadTestRespondentUniqueCodesRequest'
            example:
              respondent_unique_codes:
              - test-code-alpha-001
              - test-code-beta-002
              - test-code-gamma-003
      responses:
        '200':
          description: Returns a summary of the upload operation, including the number of new codes that were successfully added. Codes that were duplicates or already existed are ignored and not counted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadTestRespondentUniqueCodesResponse'
              example:
                uploaded_count: 3
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '429':
          $ref: '#/components/responses/Error_RateLimit'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /demand/accounts/{account_id}/target-groups/{target_group_id}/respondent-unique-codes/test/stats:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      operationId: get_test_respondent_unique_codes_stats
      summary: Get test respondent unique code stats
      description: 'This endpoint returns a summary of the usage for **test** respondent unique codes for a specific target group. The response includes the total number of codes stored and the count of those that remain unconsumed.


        :::caution Feature Access

        This feature must be enabled for your account. If it''s not enabled, this endpoint will return a `403 Forbidden` error. Please contact your account manager for more information.

        :::

        '
      parameters:
      - $ref: '#/components/parameters/AccountID'
      - $ref: '#/components/parameters/TargetGroupID'
      tags:
      - Respondent Unique Codes
      responses:
        '200':
          description: Returns the total and unconsumed counts of test respondent unique codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTestRespondentUniqueCodesStatsResponse'
              example:
                total_count: 500
                unconsumed_count: 450
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '429':
          $ref: '#/components/responses/Error_RateLimit'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /demand/accounts/{account_id}/target-groups/{target_group_id}/respondent-unique-codes/test/unconsumed:
    parameters:
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    delete:
      operationId: delete_unconsumed_test_respondent_unique_codes
      summary: Delete all unconsumed test respondent unique codes
      description: 'This endpoint permanently deletes all unconsumed **test** respondent unique codes for a specific target group. These are the codes associated with the test URL that were previously added via the upload endpoint.


        :::caution Feature Access

        This feature must be enabled for your account. If it''s not enabled, this endpoint will return a `403 Forbidden` error. Please contact your account manager for more information.

        :::

        '
      parameters:
      - $ref: '#/components/parameters/AccountID'
      - $ref: '#/components/parameters/TargetGroupID'
      tags:
      - Respondent Unique Codes
      responses:
        '204':
          description: Confirms that all unconsumed test respondent unique codes were deleted successfully.
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '429':
          $ref: '#/components/responses/Error_RateLimit'
        '500':
          $ref: '#/components/responses/Error_Internal'
components:
  schemas:
    UploadTestRespondentUniqueCodesResponse:
      type: object
      required:
      - uploaded_count
      properties:
        uploaded_count:
          type: integer
          minimum: 0
          maximum: 20000
          description: The number of respondent unique codes that were newly uploaded.
          example: 1000
    GetLiveRespondentUniqueCodesStatsResponse:
      type: object
      required:
      - total_count
      - unconsumed_count
      properties:
        total_count:
          type: integer
          minimum: 0
          description: The total number of respondent unique codes in the target group.
          example: 1000
        unconsumed_count:
          type: integer
          minimum: 0
          description: The count of respondent unique codes that have not yet been consumed.
          example: 32
    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
    Traceparent:
      type: string
      description: 'The traceparent header carries essential trace context information. This includes the trace ID and parent span ID  as defined by the W3C trace context specification. It is used to pinpoint the position of an incoming request within  the trace graph, facilitating the tracking of distributed operations.

        Note: This field is optional and will be automatically generated by the service if not provided in the request.  The generated value will be included in the response header.'
      example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
    UploadTestRespondentUniqueCodesRequest:
      type: object
      required:
      - respondent_unique_codes
      properties:
        respondent_unique_codes:
          type: array
          minItems: 1
          maxItems: 20000
          description: A list of unique codes to upload for the target group.
          items:
            type: string
            minLength: 1
            maxLength: 128
            description: A unique code, between 1 and 128 characters.
            example: respondent-unique-code-12345
          example:
          - respondent-unique-code-12345
          - respondent-unique-code-67890
          - respondent-unique-code-ABCDE
    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'
    UploadLiveRespondentUniqueCodesRequest:
      type: object
      required:
      - respondent_unique_codes
      properties:
        respondent_unique_codes:
          type: array
          minItems: 1
          maxItems: 20000
          description: A list of unique codes to upload for the target group.
          items:
            type: string
            minLength: 1
            maxLength: 128
            description: A respondent unique code to be uploaded.
            example: respondent-unique-code-12345
          example:
          - respondent-unique-code-12345
          - respondent-unique-code-67890
          - respondent-unique-code-ABCDE
    Tracestate:
      type: string
      description: 'The tracestate header provides additional contextual information to the traceparent header.  This enriches the tracing context and offers more fine-grained control

        Note: This field is optional and will be automatically generated by the service if not provided in the request.  The generated value will be included in the response header.'
      example: ot=foo:bar;k1:13
    UploadLiveRespondentUniqueCodesResponse:
      type: object
      required:
      - uploaded_count
      properties:
        uploaded_count:
          type: integer
          minimum: 0
          maximum: 20000
          description: The number of respondent unique codes that were newly uploaded.
          example: 1000
    AccountID:
      description: The account's unique identifier.
      type: integer
      format: int32
      example: 101
    GetTestRespondentUniqueCodesStatsResponse:
      type: object
      required:
      - total_count
      - unconsumed_count
      properties:
        total_count:
          type: integer
          minimum: 0
          description: The total number of respondent unique codes in the target group.
          example: 1000
        unconsumed_count:
          type: integer
          minimum: 0
          description: The count of respondent unique codes that have not yet been consumed.
          example: 32
    TooManyRequestsProblemDetails:
      type: object
      title: Too many requests problem details
      description: The error payload returned when the rate limit has been exceeded.
      required:
      - object
      - details
      properties:
        object:
          type: string
          description: A machine-readable string identifying the type of error.
          enum:
          - too_many_requests_problem_details
        details:
          type: string
          description: A human-readable message explaining that the rate limit was exceeded.
  responses:
    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_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_RateLimit:
      description: The request was rate limited. Please retry after the specified delay.
      headers:
        traceparent:
          description: The `traceparent` header carries the trace ID and parent span ID, as defined by the W3C Trace Context specification. It's used to trace a single request as it moves through multiple services.
          required: false
          schema:
            $ref: '#/components/schemas/Traceparent'
        tracestate:
          description: The `tracestate` header complements the `traceparent` header by carrying vendor-specific trace information. This allows different services to add their own data to a trace.
          required: false
          schema:
            $ref: '#/components/schemas/Tracestate'
        retry-After:
          description: The number of seconds to wait before making a follow-up request.
          schema:
            type: integer
            format: int32
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsProblemDetails'
    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`.

        '
    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'
    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