Cint Manage Profiles for Launched Target Groups API

openapi: 3.0.3
info:
  title: Demand Accounts Manage Profiles for Launched Target Groups 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: Manage Profiles for Launched Target Groups
  description: Management of Target Group profiles after launch—including creating, updating, retrieving, and deleting profile configurations, along with their conditions, quotas, and interlock settings.
paths:
  /demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/profiles:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/ProjectID'
    - $ref: '#/components/parameters/TargetGroupID'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      operationId: list_profiles
      summary: List profiles for a target group
      tags:
      - Manage Profiles for Launched Target Groups
      description: Returns a list of all non-control, blended and regular profiles for the target group after launch.
      responses:
        '200':
          description: Successfully return list of profiles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilesResponseV3'
        '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}/projects/{project_id}/target-groups/{target_group_id}/profiles/{profile_id}:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/ProjectID'
    - $ref: '#/components/parameters/TargetGroupID'
    - $ref: '#/components/parameters/ProfileIDV2'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    get:
      operationId: get_profile
      summary: Retrieve a profile
      tags:
      - Manage Profiles for Launched Target Groups
      description: Returns a regular profile detail or blended profile detail by profile ID.
      responses:
        '200':
          description: Successfully return the profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegularProfileV3'
        '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}/projects/{project_id}/target-groups/{target_group_id}/profiles/completes-goal:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/ProjectID'
    - $ref: '#/components/parameters/TargetGroupID'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    put:
      operationId: update_profile_filling_goal
      summary: Update completes goal on a target group and its profiles
      tags:
      - Manage Profiles for Launched Target Groups
      description: 'Updates the completes goal for a target group, both at the root target group level level and for individual quotas.


        Key behaviors:


        * You can update the target group `completes_goal`, individual quota goals within `profiles`, or both in a single request.

        * If you only update the total `completes_goal`, the goals for individual quotas will be recalculated based on supplier distribution data.

        * To get the necessary `profile_id` and `id` (for the quota), you must first call the `GET /.../profiles` endpoint.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FillingGoalUpdateRequestV3'
      responses:
        '200':
          description: Successfully updated the filling goal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilesResponseV3'
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationStructureErrorResponseDemographics'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/profiles/delete-profiles:
    parameters:
    - $ref: '#/components/parameters/ProjectID'
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/TargetGroupID'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    post:
      operationId: batch_delete_profiles
      summary: Delete profiles
      tags:
      - Manage Profiles for Launched Target Groups
      description: Allows the user to delete multiple profiles and quotas associated to the profile on a target group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchProfileDeletionRequestV3'
      responses:
        '204':
          description: Successfully deleted profiles
        '400':
          $ref: '#/components/responses/Error_BadRequest'
        '401':
          $ref: '#/components/responses/Error_Unauthorized'
        '403':
          $ref: '#/components/responses/Error_Forbidden'
        '404':
          $ref: '#/components/responses/Error_NotFound'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationStructureErrorResponseDemographics'
        '500':
          $ref: '#/components/responses/Error_Internal'
  /demand/accounts/{account_id}/projects/{project_id}/target-groups/{target_group_id}/profiles/manage-profiles:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/ProjectID'
    - $ref: '#/components/parameters/TargetGroupID'
    - $ref: '#/components/parameters/CintAPIVersion-2025-12-18'
    post:
      operationId: manage_target_group_profiles
      summary: Manage a target group's profiles
      tags:
      - Manage Profiles for Launched Target Groups
      description: "Replaces all profiles on a launched target group with the set of profiles provided in the request.\n\n:::warning \nThis is a destructive \"all or nothing\" operation. Any existing profiles on the target group that are not included in this request will be deleted.\n:::\n\nThe request is fully validated before any changes are applied. If any profile in the request is invalid, the entire operation is halted, and no changes are made to the target group.\n\nThe API automatically removes duplicate open-ended values in this request before validation and saving, but rejects duplicates in selection or range conditions.\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManageProfilesRequestV3'
      responses:
        '201':
          description: Successfully applied profiles to the target group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilesResponseV3'
        '400':
          $ref: '#/components/responses/Error_BadRequest_DemandAPI'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseDemographics'
        '500':
          $ref: '#/components/responses/Error_Internal_DemandAPI'
components:
  schemas:
    ClientErrorDemandAPI:
      type: object
      properties:
        object:
          type: string
        title:
          type: string
        detail:
          type: string
        invalid_params:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              reason:
                type: string
            required:
            - name
            - reason
        instance:
          type: string
        type:
          type: string
      required:
      - object
      - detail
    RegularProfileV3:
      oneOf:
      - title: Regular Profile
        type: object
        required:
        - object
        - id
        - quotas_enabled
        - name
        - description
        - targets
        properties:
          object:
            type: string
            description: Object field to distinguish the operation.
            enum:
            - regular
            example: regular
          id:
            type: string
            description: The unique identifier for the profile.
            format: ULID
            example: 01JQM2QN1FDN1WZA3JZX639MAR
          quotas_enabled:
            type: boolean
            description: Flag indicating if quotas are enabled.
            example: true
          name:
            type: string
            description: The name of the profile.
            example: HISPANIC
          description:
            type: string
            description: A short summary of the profile. Summary language will be based on the target group's locale.
            example: Are you of Hispanic, Latino, or Spanish origin?
          description_translated:
            type: string
            description: A short summary of the profile by default english language.
            example: Are you of Hispanic, Latino, or Spanish origin?
          targets:
            $ref: '#/components/schemas/QuotaV3'
      - title: Blended Profile
        type: object
        required:
        - object
        - id
        - quotas_enabled
        - name
        - description
        - targets
        properties:
          object:
            type: string
            description: Object field to distinguish the operation.
            enum:
            - blended
            example: blended
          blended_type:
            type: string
            description: The blended_type field defines the functional behavior of the blended profile as either interlock or control. If omitted, the system defaults to interlock. This field distinguishes between profiles requiring a full matrix expansion (interlock) and those used for isolating specific demographic segments (control).
            enum:
            - interlock
            - control
            example: interlock
          id:
            type: string
            description: The unique identifier for the profile.
            format: ULID
            example: 01JQM2QN1FDN1WZA3JZX639MAR
          quotas_enabled:
            type: boolean
            description: Flag indicating if quotas are enabled.
            example: true
          name:
            type: string
            description: The name of the profile.
            example: HISPANIC
          description:
            type: string
            description: A short summary of the profile. Summary language will be based on the target group's locale.
            example: Are you of Hispanic, Latino, or Spanish origin?
          description_translated:
            type: string
            description: A short summary of the profile by default english language.
            example: Are you of Hispanic, Latino, or Spanish origin?
          targets:
            $ref: '#/components/schemas/QuotaV3'
    InvalidParamStructure:
      title: Invalid request structure
      type: object
      description: An error related to the structure of the request payload itself.
      required:
      - error_type
      - name
      - reason
      properties:
        error_type:
          type: string
          description: The type of validation error.
          enum:
          - structural_error
        name:
          type: string
          description: Error name.
        reason:
          type: string
          description: Error reason.
        detail:
          type: string
    CompletesGoal:
      type: number
      description: Specifies the target group's required number of survey completions or pre-screen responses.  Formerly referred to as the "filling goal," this value sets the benchmark for the number of valid responses  needed to achieve the desired level of data reliability.
      format: int
      minimum: 1
      example: 1500
    FillingGoalUpdateRequestV3:
      oneOf:
      - title: Only total completes goal
        type: object
        description: Completes goal update request.
        required:
        - completes_goal
        properties:
          completes_goal:
            $ref: '#/components/schemas/CompletesGoal'
          profiles:
            type: array
            description: A list of profiles and filling goals with the associated profile IDs
            nullable: true
            minItems: 0
            maxItems: 0
            items:
              type: object
              properties:
                profile_id:
                  $ref: '#/components/schemas/ProfileID'
                quotas:
                  type: array
                  description: A list of filling goals with the associated quota IDs
                  items:
                    type: object
                    properties:
                      quota_id:
                        type: string
                        description: The quota ID of the quota being updated
                        example: '1234'
                      completes_goal:
                        $ref: '#/components/schemas/CompletesGoal'
      - title: Only profile specific completes goal
        type: object
        description: Completes goal update request.
        required:
        - profiles
        properties:
          completes_goal:
            type: number
            nullable: true
          profiles:
            type: array
            description: A list of profiles and completes goals with the associated profile IDs
            minItems: 1
            maxItems: 1500
            uniqueItems: true
            items:
              type: object
              required:
              - profile_id
              - targets
              properties:
                profile_id:
                  $ref: '#/components/schemas/ProfileID'
                targets:
                  type: array
                  description: A list of filling goals with the associated quota IDs
                  minItems: 1
                  maxItems: 200
                  uniqueItems: true
                  items:
                    type: object
                    required:
                    - id
                    - quota
                    properties:
                      id:
                        type: string
                        format: ULID
                        description: The quota ID of the quota being updated
                        example: 01HW8NWD653V44M5FXWD5FJD9Q
                      quota:
                        type: object
                        required:
                        - completes_goal
                        properties:
                          completes_goal:
                            $ref: '#/components/schemas/CompletesGoal'
      - title: Both
        type: object
        description: Completes goal update request.
        required:
        - completes_goal
        - profiles
        properties:
          completes_goal:
            $ref: '#/components/schemas/CompletesGoal'
          profiles:
            type: array
            description: A list of profiles and filling goals with the associated profile IDs
            minItems: 1
            maxItems: 1500
            uniqueItems: true
            items:
              type: object
              required:
              - profile_id
              - targets
              properties:
                profile_id:
                  $ref: '#/components/schemas/ProfileID'
                targets:
                  type: array
                  description: A list of completes goals with the associated quota IDs
                  minItems: 1
                  maxItems: 200
                  uniqueItems: true
                  items:
                    type: object
                    required:
                    - id
                    - quota
                    properties:
                      id:
                        type: string
                        format: ULID
                        description: The quota ID of the quota being updated
                        example: 01HW8NWD653V44M5FXWD5FJD9Q
                      quota:
                        type: object
                        required:
                        - completes_goal
                        properties:
                          completes_goal:
                            $ref: '#/components/schemas/CompletesGoal'
      example:
        completes_goal: 150
        profiles:
        - profile_id: 01K3VKDD5V7RASKQEHCA8RTGRD
          targets:
          - id: 01K3VKDD5V7RASKQEHCA8RTGRE
            quota:
              completes_goal: 45
    QuotaV3:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/QuotaDetailsV3'
    RequestDraftQuotaPercentageV3:
      type: object
      description: Profile target with condition or conditions and percentage value in quota.
      required:
      - conditions
      - quota
      properties:
        conditions:
          type: array
          description: List of conditions for the target.
          minItems: 1
          items:
            $ref: '#/components/schemas/InterlockProfileConditionsV3'
        quota:
          type: object
          required:
          - completes_goal_percentage
          properties:
            name:
              type: string
              description: Name of the quota used for tracking. This will be deprecated, functionally replaced by the `target.name` field one layer up in the contract.
              deprecated: true
              example: SF_Quota_12
            completes_goal_percentage:
              type: number
              multipleOf: 0.01
              minimum: 0
              maximum: 100
              description: Percentage of total completes goal quota applied to this condition(s).
              example: 40
    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
    ProfileTargetsResponseSelectionConditionsV3:
      type: object
      required:
      - object
      - question_id
      - option
      properties:
        object:
          type: string
          description: Object field to distinguish between different types of control selections.  Always is `selection`.
          enum:
          - selection
          example: selection
        question_id:
          $ref: '#/components/schemas/QuestionID'
        option:
          type: string
          description: the identifier for the condition
          example: '1'
        condition_name:
          type: string
          description: The name of the condition. This field will be present if the condition is part of a blended or grouped target.
          example: Dogs
        condition_name_translated:
          type: string
          description: The name of the condition translated (when appropriate and available). This field will be present if the condition is part of a blended or grouped target.
          example: Perros
    ProfileID:
      type: string
      description: Profile identifier
      example: 01K4X9PNVF1ZFA7F1DSN1ZJWWK
    QuestionID:
      type: integer
      description: The unique identifier for a profiling question.
      example: 12413
    ProfileIDV2:
      type: string
      format: ULID
      description: Profile identifier
      example: 01HY0PYB3TW23RQRVNFYRC2PP6
    ProfileTargetsResponseRangeConditionsV3:
      type: object
      required:
      - object
      - question_id
      - min
      - max
      properties:
        object:
          type: string
          description: Object field to distinguish between different types of control selections.  Always is `range`.
          enum:
          - range
          example: range
        question_id:
          $ref: '#/components/schemas/QuestionID'
        min:
          type: integer
          format: int32
          minimum: 1
          maximum: 99
          description: The minimum numeric value (inclusive).
          example: 18
        max:
          type: integer
          format: int32
          minimum: 1
          maximum: 99
          description: The maximum numeric value (inclusive).
          example: 24
        condition_name:
          type: string
          description: The name of the condition. This field will be present if the condition is part of a blended or grouped target.
          example: 18 to 24
        condition_name_translated:
          type: string
          description: The name of the condition translated (when appropriate and available). This field will be present if the condition is part of a blended or grouped target.
          example: 18 to 24
    TargetGroupID:
      description: A unique identifier for the target group, in ULID format.
      type: string
      pattern: ^[0-9A-Z]{26}$
      example: 01BTGNYV6HRNK8K8VKZASZCFP1
    QuotaDetailsV3:
      oneOf:
      - title: Targets with conditions and quota
        type: object
        description: Targets with conditions and quota.
        required:
        - id
        - conditions
        - quota
        properties:
          id:
            type: string
            description: The unique identifier for the quota.
            format: ULID
            example: 01JQMD8R7F0VW45KPWQ7WYNCFP
          name:
            type: string
            description: The name of the target.
            example: Target-Male
          text:
            type: string
            description: Text of the used for display purpose.
            example: Condition Text
          text_translated:
            type: string
            description: Translated text of the condition used for display purpose.
            example: Condition Text
          conditions:
            type: array
            description: List of conditions.
            minItems: 1
            items:
              $ref: '#/components/schemas/ResponseProfileConditionsV3'
          quota:
            type: object
            required:
            - completes_goal_percentage
            - quota_nominal
            - completes_goal
            properties:
              name:
                type: string
                description: Name of the quota used for tracking. This will be deprecated, functionally replaced by the `target.name` field one layer up in the contract.
                deprecated: true
                example: SF_Quota_12
              completes_goal_percentage:
                type: number
                multipleOf: 0.01
                minimum: 0
                maximum: 100
                description: Percentage of total completes goal quota applied to this condition(s).
                example: 40
              quota_nominal:
                type: integer
                minimum: 0
                description: Total desired quota nominal applied to this condition(s).
                example: 40
              completes_goal:
                type: integer
                minimum: 0
                description: Total desired completes goal applied to this condition(s).
                example: 40
              completes:
                type: integer
                minimum: 0
                description: Actual completes filled by responded or supplier.
                example: 40
              prescreens:
                type: integer
                minimum: 0
                description: Actual prescreens filled by responded or supplier.
                example: 40
      - title: No quota
        type: object
        description: Targets with conditions and quota.
        required:
        - id
        - conditions
        properties:
          id:
            type: string
            description: The unique identifier for the quota.
            format: ULID
            example: 01JQMD8R7F0VW45KPWQ7WYNCFP
          name:
            type: string
            description: The name of the target.
            example: Target Name
          text:
            type: string
            description: Text of the used for display purpose.
            example: Condition Text
          text_translated:
            type: string
            description: Translated text of the condition used for display purpose.
            example: Condition Text
          conditions:
            type: array
            description: List of conditions for the quota.
            minItems: 1
            items:
              $ref: '#/components/schemas/InterlockProfileConditionsV3'
    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
    InvalidParamData:
      title: Invalid request data
      type: object
      description: An error related to invalid business logic or data values.
      required:
      - error_type
      - name
      - reason
      properties:
        error_type:
          type: string
          description: The type of validation error.
          enum:
          - data_validation_error
        name:
          type: string
          description: Error name code.
          enum:
          - profile_validation_error_001
          - profile_validation_error_002
          - profile_validation_error_003
          - profile_validation_error_004
          - profile_validation_error_005
          - profile_validation_error_006
          - profile_validation_error_007
          - profile_validation_error_008
          - profile_validation_error_009
          - profile_validation_error_010
          - profile_validation_error_011
          - profile_validation_error_012
          - profile_validation_error_013
          - profile_validation_error_014
          - profile_validation_error_015
          - profile_validation_error_016
          - profile_validation_error_017
          - profile_validation_error_018
          - profile_validation_error_019
          - profile_validation_error_020
          - profile_validation_error_021
          - profile_validation_error_023
          - profile_validation_error_024
          - profile_validation_error_025
          - profile_validation_error_026
          - profile_validation_error_030
          - profile_validation_error_032
          - profile_validation_error_033
          - profile_validation_error_034
          - profile_validation_error_035
          - profile_validation_error_036
          - profile_validation_error_037
          - profile_validation_error_038
          - profile_validation_error_039
          - profile_validation_error_040
          - profile_validation_error_041
          - profile_validation_error_042
          - profile_validation_error_043
          - profile_validation_error_044
          - profile_validation_error_045
          - profile_validation_error_046
          - profile_validation_error_047
          - profile_validation_error_048
          - profile_validation_error_049
          - profile_validation_error_050
          - profile_validation_error_051
          - profile_validation_error_052
          - profile_validation_error_053
          - profile_validation_error_054
          - profile_validation_error_055
          - profile_validation_error_056
          - profile_validation_error_057
          - profile_validation_error_058
          - profile_validation_error_059
          - profile_validation_error_060
          - profile_validation_error_061
          - profile_validation_error_062
          - profile_validation_error_063
          - profile_validation_error_064
          - profile_validation_error_065
          - profile_validation_error_066
          - profile_validation_error_067
          - profile_validation_error_068
          - profile_validation_error_070
          - profile_validation_error_071
          - profile_validation_error_072
          - profile_validation_error_073
          - profile_validation_error_074
          - profile_validation_error_075
          - profile_validation_error_076
          - profile_validation_error_077
          - profile_validation_error_078
        reason:
          type: string
          description: Error reason code.
          enum:
          - profile_condition_min_greater_than_max_001
          - profile_condition_max_less_than_min_error_002
          - profile_condition_not_unique_003
          - quota_indexes_out_of_bounds_004
          - group_quota_not_unique_005
          - profile_not_unique_006
          - ungroup_quota_not_unique_007
          - quota_percentage_not_in_sync_with_nominal_008
          - incorrect_sum_of_percentage_009
          - incorrect_sum_of_nominal_010
          - unable_to_add_dependency_011
          - profile_with_invalid_condition_012
          - not_supported_profile_type_013
          - profile_condition_ranges_should_not_overlap_014
          - invalid_question_id_015
          - total_completes_goal_cannot_be_less_than_one_016
          - total_completes_goal_cannot_be_greater_than_max_017
          - invalid_zip_code_018
          - not_supported_question_option_020
          - zip_not_supported_in_blended_021
          - blended_profiles_cannot_have_more_than_3_questions_023
          - number_of_quotas_in_blended_cannot_be_greater_than_max_024
          - quota_will_be_always_enabled_for_blended_profile_025
          - at_least_one_quota_object_should_be_populated_with_completes_goal_or_completes_goal_percentage_value_026
          - total_number_of_quotas_cannot_be_greater_than_max_030
          - invalid_open_ended_option_032
          - quota_conditions_out_of_bounds_033
          - blended_profile_cannot_be_more_than_1_034
          - start_at_and_end_at_cannot_be_same_035
          - end_at_cannot_be_before_start_at_036
          - invalid_start_at_or_end_at_date_format_037
          - zip_values_cannot_be_greater_than_max_038
          - duplicate_condition_039
          - template_lo

# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cint/refs/heads/main/openapi/cint-manage-profiles-for-launched-target-groups-api-openapi.yml