POST /players/impanel

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

---

Request

Headers

Name	Required	Description
X-Api-Token	✅	Your API token.
X-User-Identifier	✅	Unique user identifier.
X-Device-Identifier	❌	Optional hardware/device ID for multi-device distinction.

---

Body Parameters (JSON)

Name	Type	Required	Description
country_id	Integer	✅	Country ID from /countries.
profile_data	Array	✅	Array of qualification responses from /qualifications.
ts	Integer	✅	Current Unix timestamp (in seconds).
sech	String	✅	SHA-256 hash of user_identifier:timestamp, signed with your API secret.
attributes_hash	Object	❌	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 or text values, depending on the question type.

---

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
• Values can be strings, numbers, or booleans
• Attributes are persisted and may influence downstream campaign eligibility

Example

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

---

Example Request

{
  "country_id": 1,
  "profile_data": [
    {
      "question_id": 42,
      "values": [25]
    },
    {
      "question_id": 43,
      "values": [1, 2]
    },
    {
      "question_id": 44,
      "values": ["94568"]
    }
  ],
  "attributes_hash": {
    "is_new_user": true,
    "subscription_tier": "premium"
  },
  "ts": 1713456789,
  "sech": "a3f9b6c40b31..."
}

---

Response

A successful impanelment returns:

{ "success": true }

If there's an issue, an error object is returned with details:

{ "error": "Invalid security hash" }

---

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 computed as a SHA-256 digest of user_identifier:ts using 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.