Impanel / player profile

The impanel endpoint ingests a participant's demographic and qualification data. TapResearch's targeting system uses it to determine which surveys the participant is eligible for. Call this endpoint before requesting surveys so that /campaigns can return only the campaigns the participant qualifies for.

POST https://api.tapresearch.com/supply_api/v4/players/impanel

Request

Headers

Name	Required	Description
X-Api-Token	Yes	Your API token.
X-User-Identifier	Yes	Your unique, stable participant identifier.
X-Device-Identifier	No	Optional hardware/device ID for multi-device distinction.

Body parameters (JSON)

Name	Type	Required	Description
country_id	Integer	Yes	Country ID from /countries.
profile_data	Array	Yes	Qualification responses from /qualifications. Must not be empty.
ts	Integer	Yes	Current Unix timestamp (in seconds).
sech	String	Yes	HMAC-SHA256 (hex) of <X-User-Identifier>:<ts>, keyed with your API secret. See Security hash.
attributes_hash	Object	No	Key-value map of custom publisher-defined attributes used for segmentation.

Profile data format

Each object in profile_data represents a qualification and its responses.

Field	Type	Description
question_id	Integer	ID of the qualification question.
values	Array	Selected pre_code integers for select questions, or a single text value for Text questions.

Segmentation

The optional attributes_hash field allows publishers to attach custom attributes to a user profile at impanel time.

These attributes can be used for segmentation and targeting within TapResearch's system.

• Keys are defined by the publisher, but can't start with tapresearch_ (reserved)
• Values can be strings or numbers
• Attributes are persisted and may influence downstream campaign eligibility

Example

"attributes_hash": {
  "is_new_user": "true",
  "subscription_tier": "premium",
  "days_since_signup": 3
}

See Segmentation for how attributes are stored and matched.

Example request

{
  "country_id": 1,
  "profile_data": [
    {
      "question_id": 50017,
      "values": ["1990-04-12"]
    },
    {
      "question_id": 43,
      "values": [1]
    },
    {
      "question_id": 45,
      "values": ["94568"]
    }
  ],
  "attributes_hash": {
    "is_new_user": "true",
    "subscription_tier": "premium"
  },
  "ts": 1713456789,
  "sech": "a3f9b6c40b31..."
}

Response

A successful impanelment returns 200 OK:

{ "success": true }

Errors return a JSON error or message. Coded errors also include error_code.

Status	Meaning
401	Missing or invalid API token.
422	Missing or invalid request parameters.
503	Temporarily unavailable.

Notes

• The API secret must never be included in the request — only use it server-side to generate the sech hash.
• Use the pre_code values from /qualifications for Single select and Multi select data points.
• The sech is an HMAC-SHA256 hex digest of user_identifier:ts, keyed with your API secret.
• Both ts and sech must be provided as JSON fields in the request body.
• Call this endpoint before retrieving campaigns from /campaigns.
• A 200 OK response with "success": true confirms the participant has been impaneled successfully.
• attributes_hash is optional — if omitted, no custom segmentation attributes are applied.

---

Next step: Fetch surveys → — retrieve the campaigns the participant qualifies for.