Skip to main content
Version: 2025-05-27

How to implement fielding assistant on a draft target group

This guide explains how to enable and configure various fielding assistant features (like "prevent overfill" and "balanced fill") when you create a new target group in draft status.

The fielding assistant offers smart tools to optimize your survey's fieldwork performance, helping to prevent over-collection, ensure balanced respondent distribution, and manage costs or pacing. Implementing these settings from the start helps automate fieldwork management.

Steps to configure fielding assistant in a draft target group​

You can configure fielding assistant settings within the fielding_assistant_assignment object in the request body of the create a target group in draft status endpoint.

Step 1: Prepare your target group request body​

Construct the JSON payload for creating your new draft target group. This will include all standard target group parameters, plus the fielding_assistant_assignment object where you enable the desired features.

  • API endpoint: POST https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups
  • Request body section: You'll be focusing on populating the "fielding_assistant_assignment" object within the main request body.

This example enables "prevent overfill" and "balanced fill."

Example JSON request body for a draft target group with fielding assistant enabled:

  {
    "name": "My Optimized target group",
    "business_unit_id": "<YOUR_BUSINESS_UNIT_ID>",
    "project_manager_id": "<YOUR_PROJECT_MANAGER_ID>",
    "study_type_code": "adhoc",
    "industry_code": "other",
    "cost_per_interview": {
      "value": "2.7352",
      "currency_code": "USD"
    },
    "locale": "eng_us",
    "collects_pii": false,
    "filling_goal": 100,
    "expected_length_of_interview_minutes": 5,
    "expected_incidence_rate": 0.20,
    "fielding_specification": {
      "start_at": "2025-07-25T08:00:00.000Z",
      "end_at": "2025-08-01T23:59:59.000Z"
    },
    "fielding_assistant_assignment": {
      "quota_overlay": {
        "prevent_overfill": true,
        "balance_fill": true
      }
    },
    "profile": {
      "profile_adjustment_type": "percentage",
      "drafts": [],
      "interlocked_profiles": []
    },
    "exclusion": {
      "enabled": false,
      "list": []
    }
  }

Key fielding_assistant_assignment parameters​

  • quota_overlay (object): Controls how quotas are managed.
    • prevent_overfill (boolean): Set to true to convert the complete target to a prescreen quota, preventing over-collection. Recommended
    • balance_fill (boolean): Set to true to distribute completes evenly across quotas, preventing skew.
  • pricing (object, optional): Defines the pricing model. Must be one of the following types:
    • Dynamic pricing: Optimizes the CPI. Requires type to be set to "dynamic".
      • type (string): Must be "dynamic".
      • total_budget (object, optional): Overall budget for the target group.
      • maximum_cpi (object, optional): Maximum cost per interview.
      • minimum_cpi (object, optional): Minimum cost per interview.
      • Note: You typically define either total_budget or maximum_cpi.
    • Rate card pricing: Uses defined rates. Requires type to be set to "rate_card".
      • type (string): Must be "rate_card".
      • maximum_cpi (object, optional): Maximum cost per interview.
      • boost_cpi (object, optional): Additional amount to be added to the CPI inferred from the rate card. Respects maximum CPI.
  • pacing (object, optional): Controls the rate of completes.
    • type (string): "linear" or "adaptive".
    • increment_interval (string): ISO 8601 duration (e.g., "P1D" for one day, "PT30M" for 30 minutes).

Step 2: Send the create target group request​

Execute the API call to create your draft target group with the configured fielding assistant settings.

  • Request headers:
    • Content-Type: application/json
    • Authorization: Bearer <YOUR_JWT_TOKEN>
    • Cint-API-Version: 2025-05-27 (or the latest stable version)

Example cURL request:

curl -X POST \
  'https://api.cint.com/v1/demand/accounts/{account_id}/projects/{project_id}/target-groups' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Cint-API-Version: 2025-05-27' \
  -d '{
    "name": "My Optimized target group",
    "business_unit_id": "<YOUR_BUSINESS_UNIT_ID>",
    "project_manager_id": "<YOUR_PROJECT_MANAGER_ID>",
    "study_type_code": "adhoc",
    "industry_code": "other",
    "cost_per_interview": {
      "value": "2.7352",
      "currency_code": "USD"
    },
    "locale": "eng_us",
    "collects_pii": false,
    "filling_goal": 100,
    "expected_length_of_interview_minutes": 5,
    "expected_incidence_rate": 0.20,
    "fielding_specification": {
      "start_at": "2025-07-25T08:00:00.000Z",
      "end_at": "2025-08-01T23:59:59.000Z"
    },
    "live_url": "https://mytestsurvey.com/?RID=[%RID%]",
    "test_url": "https://mytestsurvey.com/?RID=[%RID%]",
    "fielding_assistant_assignment": {
      "quota_overlay": {
        "prevent_overfill": true,
        "balance_fill": true
      }
    },
    "profile": {
      "profile_adjustment_type": "percentage",
      "drafts": [], // Add your profile definitions here
      "interlocked_profiles": []
    },
    "exclusion": {
      "enabled": false,
      "list": []
    }
  }'
note

Remember to replace all bracketed placeholders (e.g., <YOUR_ACCOUNT_ID> and <YOUR_PROJECT_ID>) with your actual values.

Step 3: Verify target group creation and settings​

A successful request creates your draft target group. You can verify the applied fielding assistant settings by retrieving the target group.

  • Action: Make a GET call to the retrieve a target group endpoint using the target_group_id returned in the response from Step 2.
  • Purpose: To confirm that the fielding_assistant_assignment object reflects your desired configuration.
  • Outcome: The response will include the fielding_assistant_assignment object with your settings.

Example success response snippet showing fielding assistant settings:

note

This example only shows the fielding assistant object and doesn't contain all of the target group details.

{
  "id": "01JX2X0N5RTR012AYDTA83QWTW",
  "name": "My Optimized target group",
  "fielding_assistant_assignment": {
    "quota_overlay": {
      "prevent_overfill": true,
      "balance_fill": true
    },
    "pricing": null,
    "pacing": null
  },
  "status": "Draft"
}

Troubleshooting​

  • HTTP 400 Bad Request:
    • Check for typos in parameter names or incorrect data types (true/false for booleans, string for currency values, ISO 8601 for dates, etc.).
    • Ensure all required fields for target group creation are present, even those outside fielding_assistant_assignment.
    • If you're using pricing settings, ensure you are using the appropriate type of pricing setup for your account. For example, a dynamic pricing customer should correctly define either total_budget or maximum_cpi, but not both.
    • If using pacing, confirm increment_interval adheres to ISO 8601 duration format.
  • HTTP 401 Unauthorized or HTTP 403 Forbidden: Verify your JWT Token is valid and has the necessary permissions.
  • Unexpected behavior after launch: The fielding assistant settings primarily influence fieldwork once the target group is launched. If you observe unexpected behavior, review the settings using retrieves the fielding assistant assignment for a target group and consult Understanding fielding assistant for details on how each feature operates.