Promo Codes
Manage promo code lists and link them to surveys
Survey promo codes
The promo codes module allows you to restrict access to a survey, run promotions, and track conversions using code lists linked to specific surveys.
Base prefix for most endpoints: /api/v3/service/quiz/{id}/promo and /api/v3/service/promo.
Download the markdown version of the «Promo Codes» section for use in ChatGPT / other LLMs:
All endpoints
| HTTP | Endpoint | Purpose |
|---|---|---|
| GET | /quiz/{id}/promo/list | Get workspace promo code lists |
| POST | /quiz/{id}/promo/list | Create a promo code list |
| POST | /quiz/{id}/promo/list/{list_id} | Rename a list |
| DELETE | /quiz/{id}/promo/list/{list_id} | Delete a promo code list |
| GET | /promo/codes | Get codes of the selected list (global) |
| POST | /promo/codes | Add codes to a list |
| DELETE | /promo/codes/{code_id} | Delete a code |
| POST | /promo/list | Create a list (via /promo/list) |
| POST | /promo/import-file | Import codes from file |
| POST | /promo/attach/{list_id} | Attach a list to surveys |
| POST | /promo/detach | Detach a list from surveys |
| POST | /quiz/{id}/promo/sync | Synchronize list attachments |
| GET | /quiz/{id}/promo/codes/quiz | Codes of the list attached to a survey |
| GET | /quiz/{id}/promo/pinned | Surveys for the attachment screen |
Get promo code lists GET /api/v3/service/quiz/{id}/promo/list
Returns a paginated list of workspace promo code lists with the number of codes and attached surveys.
| Parameter | Type | Default | Description |
|---|---|---|---|
| search | string | — | Search by list name |
| limit | integer | 20 | Count (max 500) |
| offset | integer | 0 | Offset |
| sort | string | updated_at | id, updated_at, name |
| order | string | desc | asc or desc |
curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/promo/list?limit=20&offset=0" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Create a promo code list POST /api/v3/service/promo/list
Creates a new list with a set of codes (up to 1000 at a time).
| Parameter | Req. | Description |
|---|---|---|
| name | Yes | List name |
| codes[] | Yes | Array of promo code strings (up to 1000) |
curl -X POST "https://api.surveyninja.io/api/v3/service/promo/list" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "January Sale", "codes": ["PROMO001", "PROMO002", "PROMO003"] }'Rename a list POST /api/v3/service/quiz/{id}/promo/list/{list_id}
| Parameter | Req. | Description |
|---|---|---|
| name | Yes | New list name |
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/promo/list/45" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "February Sale" }'Delete a list DELETE /api/v3/service/quiz/{id}/promo/list/{list_id}
Deletes a promo code list along with all its codes. No request body required.
curl -X DELETE "https://api.surveyninja.io/api/v3/service/quiz/123/promo/list/45" \ -H "Authorization: Bearer YOUR_API_TOKEN"Get list codes GET /api/v3/service/promo/codes
Returns codes of the specified list with filtering and pagination. The response includes the stats and quizzes[] fields.
| Parameter | Req. | Default | Description |
|---|---|---|---|
| list_id | Yes | — | Promo code list ID |
| search | No | — | Search by code |
| used | No | — | 1 — used, 0 — unused |
| limit | No | 20 | Count (max 500) |
| offset | No | 0 | Offset |
| sort | No | id | id, updated_at, name |
| order | No | desc | asc or desc |
curl -X GET "https://api.surveyninja.io/api/v3/service/promo/codes?list_id=45&limit=20" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Add codes to a list POST /api/v3/service/promo/codes
| Parameter | Req. | Description |
|---|---|---|
| list_id | Yes | List ID |
| codes[] | Yes | Array of promo code strings |
curl -X POST "https://api.surveyninja.io/api/v3/service/promo/codes" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "list_id": 45, "codes": ["NEW001", "NEW002"] }'Delete a code DELETE /api/v3/service/promo/codes/{code_id}
Deletes an individual promo code from the list. No request body required.
curl -X DELETE "https://api.surveyninja.io/api/v3/service/promo/codes/789" \ -H "Authorization: Bearer YOUR_API_TOKEN"Import codes from file POST /api/v3/service/promo/import-file
Uploads promo codes from a file. Request format: multipart/form-data.
| Parameter | Req. | Description |
|---|---|---|
| file | Yes | File in txt, csv, xlsx, xls format. Maximum 1 MB |
Response: {"imported_count": 50, "codes": ["CODE1", ...]}
curl -X POST "https://api.surveyninja.io/api/v3/service/promo/import-file" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "file=@/path/to/codes.csv"Attach / detach a list from surveys
Manage attaching a promo code list to multiple surveys at once.
| Parameter | Req. | Description |
|---|---|---|
| quize_ids[] | Yes | Array of survey IDs |
curl -X POST "https://api.surveyninja.io/api/v3/service/promo/attach/45" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quize_ids": [123, 456] }'curl -X POST "https://api.surveyninja.io/api/v3/service/promo/detach" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quize_ids": [123] }'Synchronize attachments POST /api/v3/service/quiz/{id}/promo/sync
Atomically updates list attachments: attaches the specified surveys and detaches all others. Returns lists of changes.
| Parameter | Req. | Description |
|---|---|---|
| list_id | Yes | Promo code list ID |
| quize_ids[] | Yes | Final list of survey IDs to attach |
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/promo/sync" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "list_id": 45, "quize_ids": [123, 456, 789] }'Response example:
{ "attached": [456, 789], "detached": [100, 101] }Codes of the attached list GET /api/v3/service/quiz/{id}/promo/codes/quiz
Returns promo codes from the list attached to the specified survey. Similar to GET /promo/codes, but without needing to specify list_id.
curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/promo/codes/quiz" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Surveys for the attachment screen GET /api/v3/service/quiz/{id}/promo/pinned
Returns a list of surveys with a flag indicating whether the specified promo code list is attached to them.
| Parameter | Req. | Default | Description |
|---|---|---|---|
| list_id | Yes | — | Promo code list ID |
| search | No | — | Search by survey name |
| limit | No | 20 | Count |
| offset | No | 0 | Offset |
Response: {"total": N, "data": [{"id": 123, "name": "My Survey", "attach": true, "current": false}, ...]}
curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/promo/pinned?list_id=45&limit=20" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"