Cint Fielding Assistant API

openapi: 3.0.3
info:
  title: Demand Accounts Fielding Assistant 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: Fielding Assistant
  description: Get, update Target Group Fielding Assistant assignments. Fielding Assistant provides optional modules to automate common workflows and optimise your Target Group.
paths:
  /demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/fielding-assistant-assignment:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/ProjectID'
    - $ref: '#/components/parameters/TargetGroupID'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      operationId: get_fielding_assistant_assignment
      summary: Retrieves the Fielding Assistant assignment for a target group
      description: "Retrieves the current Fielding Assistant configuration for a target group. The response will show which modules, if any, are currently enabled. Examples:\n\n  * Pricing\n  * Quota overlay\n  * Pacing\n  * Soft launch"
      tags:
      - Fielding Assistant
      responses:
        '200':
          description: The Fielding Assistant assignment details were retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldingAssistantModulesAssignment'
              example:
                pricing:
                  type: dynamic
                  maximum_cpi":
                    value: '5.00'
                    currency_code: USD
                    currency_scale: 2
                pacing:
                  type: linear
                  increment_interval: P1D
                quota_overlay:
                  prevent_overfill": true
                  balance_fill: true
                soft_launch: null
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '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'
    put:
      operationId: create_or_update_fielding_assistant_assignment
      summary: Create or update the Fielding Assistant assignment
      description: 'Creates or fully replaces the Fielding Assistant assignment for a target group. This is an "all or nothing" operation.

        To modify an existing assignment, you must first GET the current configuration, make your changes,

        and then PUT the entire modified object back. Sending a request with only one module will disable all others.

        To disable all modules, send an empty object `{}`. This endpoint uses the `If-Match` header for optimistic locking.

        '
      tags:
      - Fielding Assistant
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      - $ref: '#/components/parameters/IfNoneMatch'
      requestBody:
        description: Fielding assistant assignment request.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldingAssistantModulesAssignmentRequestModel'
            examples:
              full_configuration:
                summary: Enable Dynamic Pricing and Linear Pacing
                description: Example configuration with dynamic pricing, linear pacing, and quota overlay modules enabled
                value:
                  pricing:
                    type: dynamic
                    maximum_cpi:
                      value: '5.00'
                      currency_code: USD
                  pacing:
                    type: linear
                    increment_interval: P1D
                  quota_overlay:
                    prevent_overfill: true
                    balance_fill: true
              disable_all:
                summary: Disable All Modules
                description: Send an empty object to disable all Fielding Assistant modules
                value: {}
      responses:
        '204':
          description: Fielding assistant assignment on target group successfully created or updated.
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '412':
          $ref: '#/components/responses/Precondition_Failed'
        '500':
          $ref: '#/components/responses/Error_Internal'
components:
  schemas:
    FieldingAssistantModulesAssignment:
      title: Fielding Assistant modules assignment
      description: A container for all enabled Fielding Assistant modules for a target group. Each module is optional; if a module is omitted or set to `null`, it is considered disabled.
      type: object
      properties:
        pricing:
          oneOf:
          - $ref: '#/components/schemas/ModuleDynamicPricing'
          - $ref: '#/components/schemas/ModuleRateCardPricing'
          nullable: true
        quota_overlay:
          allOf:
          - $ref: '#/components/schemas/ModuleQuotaOverlay'
          nullable: true
        pacing:
          oneOf:
          - $ref: '#/components/schemas/ModuleLinearPacing'
          - $ref: '#/components/schemas/ModuleAdaptivePacing'
          - $ref: '#/components/schemas/ModuleGeminiPacing'
          nullable: true
        soft_launch:
          allOf:
          - $ref: '#/components/schemas/ModuleSoftLaunch'
          nullable: true
    ModuleSoftLaunch:
      title: Soft launch
      type: object
      description: Manages a soft launch of a target group. During a soft launch, pacing modules are ignored.
      properties:
        end_at:
          type: string
          description: The soft launch will be finished at this date, and the target group paused regardless of the fill.
          format: date-time
          example: '2023-01-01T23:00:00.000Z'
        filling_goal_percentage:
          description: The percentage of the full filling goal to collect during the soft launch phase.
          type: integer
          minimum: 1
          maximum: 100
          example: 1
        demographics_strictness_percentage:
          description: Controls how strictly the soft launch's demographic distribution should follow the full launch's distribution. A value of `100` aims to match the distribution perfectly, while `0` allows any distribution.
          type: integer
          minimum: 0
          maximum: 100
          example: 1
      required:
      - end_at
      - filling_goal_percentage
      - demographics_strictness_percentage
    ETag:
      type: string
      description: The `ETag` header provides a unique identifier that represents the current version state of a particular resource.
      example: W/"1234"
    ModuleGeminiPacing:
      title: Gemini pacing
      type: object
      description: Always collects at most as many completes on each quota, as were collected on an exposed target group. Intended for Measurement control target groups.
      properties:
        type:
          type: string
          enum:
          - gemini
          description: The type of module. For this object, the value is always 'gemini'.
        exposed_target_group_id:
          type: string
          format: ulid
          description: Uniquely identifies exposed target group by ID.
          example: 01HC2Z6TM8C4F3Y5CA6S2JR475
      required:
      - type
      - exposed_target_group_id
    IncrementInterval:
      type: string
      format: duration
      example: P1DT5H
      description: 'The duration between each quota increment, in ISO-8601 format.


        Key details:


        * **Format:** Must follow the `PnDTnHnMnS` pattern (e.g., `P1D` for one day, `PT12H` for 12 hours).

        * **Limit:** The duration must be less than 398 days.

        '
    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
    ModuleDynamicPricing:
      title: Dynamic pricing
      type: object
      description: 'Controls the Cost Per Interview (CPI) to achieve a 100% fill rate by the target group''s end date as cost-effectively as possible.


        Key behaviors:


        * **Prerequisite:** This module can only be used for target groups configured with dynamic pricing.

        * You must specify either `total_budget` or `maximum_cpi`, but not both.

        * If you specify `minimum_cpi`, it must be lower than the `maximum_cpi`.

        * The `total_budget` setting can overrule the `minimum_cpi`.

        '
      properties:
        type:
          type: string
          enum:
          - dynamic
          description: The type of module. For this object, the value is always 'dynamic'.
        total_budget:
          description: The maximum total amount to spend for the target number of completes.
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
        maximum_cpi:
          description: The maximum cost per interview (CPI) that the module is allowed to set.
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
        minimum_cpi:
          description: The minimum cost per interview (CPI) that the module is allowed to set.
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
      required:
      - type
    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
    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'
    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:
          - nullable: true
          - type: integer
            description: The number of digits after the decimal separator, as defined by ISO 4217.
            example: 2
    FieldingAssistantModulesAssignmentRequestModel:
      title: Fielding Assistant modules assignment
      description: Having an assignment enables Fielding Assistant modules on a specified target group.  All modules are optional, their omission means they are not enabled.
      type: object
      properties:
        pricing:
          description: The pricing module configuration. The `type` field within the object determines the model (`dynamic` or `rate_card`).
          oneOf:
          - $ref: '#/components/schemas/ModuleDynamicPricing'
          - $ref: '#/components/schemas/ModuleRateCardPricing'
          nullable: true
        quota_overlay:
          $ref: '#/components/schemas/ModuleQuotaOverlay'
        pacing:
          description: The pacing module configuration. The `type` field within the object determines the pacing strategy (`linear`, `adaptive`, or `gemini`).
          oneOf:
          - $ref: '#/components/schemas/ModuleLinearPacing'
          - $ref: '#/components/schemas/ModuleAdaptivePacing'
          - $ref: '#/components/schemas/ModuleGeminiPacing'
          nullable: true
        soft_launch:
          $ref: '#/components/schemas/ModuleSoftLaunch'
    ProjectID:
      description: The character string representing a unique project ID (ULID format).
      type: string
      pattern: ^[0-9A-Z]{26}$
      example: 01BTGNYV6HRNK8K8VKZASZCFP0
    ModuleRateCardPricing:
      title: Rate Card pricing
      type: object
      description: Manages pricing for a target group that uses a rate card model. This module cannot be used with `dynamic` pricing.
      properties:
        type:
          type: string
          enum:
          - rate_card
          description: The type of module. For this object, the value is always 'rate_card'.
        maximum_cpi:
          description: The maximum cost per interview (CPI) that the module is allowed to set.
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
        boost_cpi:
          description: Additional amount to be added to the CPI inferred from the rate card. Respects the `maximum_cpi` setting limit.
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
      required:
      - type
    ModuleLinearPacing:
      title: Linear even pacing
      type: object
      description: Paces fielding by incrementing the completes goal in regular intervals until the target group's end date.
      properties:
        type:
          type: string
          enum:
          - linear
          description: The type of module. For this object, the value is always 'linear'.
        increment_interval:
          $ref: '#/components/schemas/IncrementInterval'
      required:
      - type
      - increment_interval
    ModuleQuotaOverlay:
      title: Quota overlay
      type: object
      description: Controls how the overall completes goal is distributed across the target group's quotas.
      properties:
        prevent_overfill:
          type: boolean
          description: When `true`, this setting helps prevent quotas from exceeding their target number of completes.
          example: true
        balance_fill:
          type: boolean
          description: Whentrue, this setting ensures that quotas within the same demographic category fill at a similar rate.
          example: true
      required:
      - prevent_overfill
      - balance_fill
    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
    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
    AccountID:
      description: The account's unique identifier.
      type: integer
      format: int32
      example: 101
    ModuleAdaptivePacing:
      title: Adaptive even pacing
      type: object
      description: Increments quotas in regular intervals, recalculating steps after each interval to evenly pace  the rest of the Completes Goal until the end date.
      properties:
        type:
          type: string
          enum:
          - adaptive
          description: The type of module. For this object, the value is always 'adaptive'.
        increment_interval:
          $ref: '#/components/schemas/IncrementInterval'
      required:
      - type
      - increment_interval
  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_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
    Precondition_Failed:
      description: The resource could not be modified because the ETag in the If-Match header does not match the current version. This means the resource was updated by another request after you retrieved it.
      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'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            id: 3d61d9c3-68ee-4026-b436-6e76a2b33932
            object: precondition_failed_error
            detail: The resource has been modified since you last retrieved it. Please fetch the latest version and try your request again.
    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:
    ProjectID:
      name: project_id
      description: A unique identifier for the project, in ULID format.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/ProjectID'
    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`.

        '
    IfNoneMatch:
      name: If-None-Match
      description: The ETag value of the resource you intend to update. This is used for optimistic locking to prevent you from accidentally overwriting changes made by someone else. You can get the ETag from a GET request for the resource. The `ETag` value should always be wrapped in double quotes, whether it is part of a weak `ETag` or standalone. Using `*` will match any version state.
      in: header
      schema:
        type: string
        format: etag
        example: '1'
    IfMatch:
      name: If-Match
      description: The ETag value of the resource you intend to update. This is used for optimistic locking to prevent you from accidentally overwriting changes made by someone else. You can get the ETag from a GET request for the resource. The `ETag` value should always be wrapped in double quotes, whether it is part of a weak `ETag` or standalone.
      in: header
      schema:
        type: string
        format: etag
        example: W/"1234"
    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'
  headers:
    ETag:
      description: The `ETag` header provides a unique identifier that represents the current version of a resource. It's used for caching and to prevent concurrent modification issues.
      required: true
      schema:
        $ref: '#/components/schemas/ETag'
  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