Quickstart
Copy-paste example — your first POST /api/v1/publishers/surveys request.
Before you run this
- API key from Settings → API keys
- Redirect URLs configured for your
appId - Your
appIdand a testpanelistId(both strings) - The panelist's age and gender (required from 2026-10-06)
Local docs: use Download collection and import the file in Postman (File → Import). Run in Postman needs the public URL at publishers.mypinio.com — Postman cannot fetch collections from localhost.
Request
Replace the placeholders and run from a machine that can reach the public internet:
curl -sS -X POST 'https://publishers.mypinio.com/api/v1/publishers/surveys' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"appId": "YOUR_APP_ID",
"panelistId": "YOUR_PANELIST_ID",
"country": "DE",
"locale": "de-DE",
"maxSurveys": 10,
"profileDetails": {
"age": 34,
"gender": "female",
"postalCode": "10115"
}
}'Alternatively, pass the key as X-API-Key: YOUR_API_KEY.
profileDetails.age and profileDetails.gender are required from 2026-10-06 — requests without them are then rejected with HTTP 400. Send them now; until that date a missing field only adds a profile_fields_required_soon warning to the response.
| Field | Allowed values |
|---|---|
age | Whole number as a JSON number (34, not "34"), 0–130 |
gender | "male" or "female" (not case-sensitive; "m", "f", "1" = male, "2" = female also accepted). Send it as a string. Other values count as present but are not used for matching. |
postalCode | Optional, recommended — improves matching |
appId and panelistId must be strings ("12345", not 12345).
Response with offers
{
"appId": "YOUR_APP_ID",
"panelistId": "YOUR_PANELIST_ID",
"country": "DE",
"locale": "de-DE",
"requestStatus": "true",
"hasSurveys": true,
"hasPartlyQuestions": false,
"surveyCount": 1,
"rewardUnitName": "PINTOS",
"surveys": [
{
"surveyId": "123456",
"entryLink": "https://…",
"cpi": 1.25,
"loi": 12,
"ir": 35,
"category": "Shopping",
"userRewardAmount": 125
}
]
}Open entryLink in a browser to start the survey flow. Field reference: POST /surveys.
Response without offers
{
"requestStatus": "true",
"hasSurveys": false,
"surveyCount": 0,
"surveys": []
}This is not an error — no surveys matched that panelist at this time.
Next steps
- Integration guide — full setup and return handling
- Redirect URLs — verify signatures on your return endpoints
- Errors — HTTP status codes