API integrations: a complete usage guide

The WiseData NPS API lets another system — your CRM, e-commerce or ERP — read and maintain your contacts and contact lists automatically, without anyone touching the panel. It's a REST API: you make HTTP requests and get JSON responses. This guide's example is a CRM that adds every new customer to the "Active customers" list.

Tokens live in Collect › Integrations, available from the Pro plan up — Free and the 14-day free trial don't include the API. Only account administrators create and revoke tokens: for other members, the screen hides the New Token button and the revoke trash icon, and says that only administrators create and revoke tokens. If the account goes back to a plan without API access, tokens stop working: the first call with each one returns 403 and the token is revoked.

Overview

• Base URL: https://api.wisedatanps.com (every path starts with /api/v1)
• Authentication: token in the Authorization: Bearer YOUR_TOKEN header
• Format: JSON in requests (with Content-Type: application/json) and in responses
• What you can do: list, create, read, update and delete contacts; list, create, read, rename and delete contact lists
• What you can't: the token only reaches contacts and lists. Surveys, responses and reports are not in the API — a call to them with a token returns 403.

Step 1 — Create a token

In Collect › Integrations, click New Token. Fill in the Token name (3 to 100 characters, e.g. "CRM integration") and, under What this token can do, check only what the integration needs:

• Read contacts — query contacts and their data.
• Create and edit contacts — add, edit and delete contacts.
• Read contact lists — query existing lists.
• Create and edit lists — create, rename and delete lists.

The form opens with both read permissions checked, and at least one must stay checked. When you check a write permission, the screen warns that it changes and removes data in your account. The example CRM needs Read contact lists (to find the list) and Create and edit contacts (to add people). Permissions can't be edited later: to change them, create a new token and revoke the old one.

Click Create Token. The token is shown only once: copy it and store it somewhere safe before clicking Got it, already copied. Use the whole value exactly as shown — it starts with a number and a slash (12|...), and that part belongs to the token.

The token is valid for 365 days. In the list, each token shows its permissions, the last digits, Created by, Created, Last used and Expires (the date is highlighted when it's close to expiring). An expired token returns 401: create a new one and swap it in the integration before the date. The administrator sees and revokes the tokens of the whole account.

If a token leaks or is no longer used, revoke it — any system using it loses access immediately. Use one token per integration so you can revoke only what you need.

Step 2 — Authenticate your requests

Send the token on every call, in the authorization header:

Authorization: Bearer YOUR_TOKEN Content-Type: application/json

Step 3 — Your first request

Start by listing your contact lists to find each one's id (permission Read contact lists):

curl https://api.wisedatanps.com/api/v1/contact-lists/all \ -H "Authorization: Bearer YOUR_TOKEN"

{ "data": [ { "id": 1, "name": "Active customers", "description": null, "contactsCount": 42, "createdAt": "2026-06-05T13:40:00.000000Z", "updatedAt": "2026-06-05T13:40:00.000000Z" } ] }

With the list's id in hand, you can read or add contacts to it.

List endpoints

List all lists

GET /api/v1/contact-lists/all — Read contact lists. Returns every list, in alphabetical order and without pagination.

List lists with pagination

GET /api/v1/contact-lists — Read contact lists. Optional parameters: search (searches the name), sort (name, created_at, updated_at or contacts_count), order (asc or desc), page and per_page (1 to 100; default 10). Without sort, the newest come first.

Read a list

GET /api/v1/contact-lists/{listId} — Read contact lists. Returns the list in data.

Create a list

POST /api/v1/contact-lists — Create and edit lists. Fields: name (required, 2 to 100 characters, not repeating another list's name in the account) and description (optional, up to 500 characters). Returns 201 with message and the list in data.

Update a list

PUT /api/v1/contact-lists/{listId} — Create and edit lists. Same fields as creation; name is required here too.

Delete a list

DELETE /api/v1/contact-lists/{listId} — Create and edit lists. Deletes the list and its contacts. A list used by an active survey isn't deleted: the response is 409, and the survey has to be paused first.

Contact endpoints

List a list's contacts

GET /api/v1/contact-lists/{listId}/contacts — Read contacts. Returns the list's contacts, paginated. Optional parameters:

• search — search by name, email or phone.
• sort — name, email, phone or created_at (default).
• order — asc or desc (default).
• page — page number.
• per_page — items per page, 1 to 100 (default 10).

The items come in data; meta carries the pagination (among other fields, current_page, per_page, total and last_page) and links carries the page URLs. Excerpt of the response:

{ "data": [ { "id": 123, "name": "John Smith", "email": "john@company.com", "phone": "+15551234567", "emailStatus": "valid", "phoneStatus": "valid", "createdAt": "2026-06-05T13:40:00.000000Z" } ], "meta": { "current_page": 1, "per_page": 10, "total": 42, "last_page": 5 } }

Create a contact

POST /api/v1/contact-lists/{listId}/contacts — Create and edit contacts. Creates a contact and adds it to the given list. Body fields:

• name — required, 2 to 100 characters.
• email — optional, must be a valid email. Disposable emails are rejected, and the same email can't repeat within a list.
• phone — optional, 8 to 20 characters. Use the international format, like +15551234567.

curl -X POST https://api.wisedatanps.com/api/v1/contact-lists/1/contacts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "John Smith", "email": "john@company.com", "phone": "+15551234567" }'

On success, the response is 201 with the created contact:

{ "message": "Contact created successfully.", "data": { "id": 123, "name": "John Smith", "email": "john@company.com", "phone": "+15551234567", "emailStatus": "pending", "phoneStatus": "pending", "createdAt": "2026-06-05T13:40:00.000000Z" } }

Email and phone start with a pending status and go through an automatic check right after. emailStatus becomes valid, invalid, catch_all, disposable or unknown; phoneStatus becomes valid when the number has WhatsApp, or not_whatsapp. Read the contact later to see the result.

Read a contact

GET /api/v1/contacts/{contactId} — Read contacts. Returns the contact in data.

Update a contact

PUT /api/v1/contacts/{contactId} — Create and edit contacts. Send only what changes among name, email and phone (same rules as creation). Changing the email or the phone sets its status back to pending and runs the check again. The response includes a message and the updated contact in data.

Delete a contact

DELETE /api/v1/contacts/{contactId} — Create and edit contacts. Removes the contact from the list. The response is just a confirmation message.

How to read responses

A single resource comes inside data; when there is an action (create, update, delete), a message comes too; and paginated listings carry data, meta and links. Resource fields are in camelCase (emailStatus, createdAt); the parameters you send are the ones shown above (per_page, created_at).

Common errors

Every error comes as JSON with message.

• 401 — missing, invalid, revoked or expired token. Check the Authorization header and that the whole value was copied.
• 402 — the account has a pending payment or a blocked subscription. The API comes back once billing is settled.
• 403 — the token lacks the call's permission (the response includes missing_abilities, for example ["contacts:write"]); the call targets a resource outside the API (only contacts and lists); the plan doesn't include the API (and the token is revoked); or whoever created the token needs to log in to the panel and accept updated terms.
• 404 — the given list or contact does not exist (or isn't in your account).
• 409 — attempt to delete a list used by an active survey.
• 422 — invalid data, including an email already in the list or a repeated list name. The body includes a message and an errors object pointing to each problematic field.
• 429 — you exceeded the request limit; wait the seconds given in the Retry-After header (see below).

Usage limits

• All requests: up to 120 per minute on Pro, 300 on Business and 600 on Enterprise (or whatever the contract sets). The limit is counted per user who created the token, adding up all of that user's tokens.
• Creating, updating and deleting contacts: on top of the limit above, up to 30 per minute.
• When you hit a limit, the API returns 429 with the Retry-After header, which says how many seconds to wait before trying again. Use that value in your integration instead of a fixed interval. The same response carries X-RateLimit-Limit (the limit) and X-RateLimit-Remaining (how many calls are left).

Best practices and security

• Never expose the token in code that runs in the browser or in public repositories — use it only from your server.
• Give the token only the permissions the integration uses: a read token handed to a vendor can't delete anything.
• For large loads, respect the 30 contacts per minute: send at a steady pace instead of firing everything at once.
• Note the Expires date and replace the token before it.

The Integrations page itself includes ready-made examples in cURL, JavaScript and PHP for you to copy and adapt.

Where to go next

• Contacts and lists — the same lists and contacts, viewed and managed in the panel.
• Integrating the survey into your app — the in-app survey, which uses public calls and needs no token.

In short: an administrator creates a token in Collect › Integrations with only the permissions needed, your integration sends that token in the Authorization header and uses the list and contact endpoints, respecting the per-minute limits and replacing the token before it expires.