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 lists automatically, without anyone touching the panel. It's a REST API: you make HTTP requests and get JSON responses. Everything is on the Integrations page, available on the Business plan.

Overview

• Base URL: https://api.wisedatanps.com
• 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 today: list, create, read, update and delete contacts, and list your contact lists

Step 1 — Create a token

On the Integrations page, click New Token, give it a name that helps identify the integration (e.g. "CRM integration") and confirm. The token is shown only once: copy it and store it somewhere safe, because it won't be shown again. After that, the list only shows a preview (the last digits), the creation date and the last use.

If a token leaks or is no longer used, revoke it — any system using it loses access immediately. Tip: 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:

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

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

Endpoints

List all lists

GET /api/v1/contact-lists/all — returns all your contact lists.

List a list's contacts

GET /api/v1/contact-lists/{listId}/contacts — returns a list's contacts, paginated. Accepted query parameters:

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

The response is paginated, with the data in data and pagination info in meta:

{   "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": 15, "total": 42, "last_page": 3 } }

Create a contact

POST /api/v1/contact-lists/{listId}/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).
• phone — optional, 8 to 20 characters.

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"   } }

Note: email and phone start with a pending status and go through an automatic check in the background — the status changes to valid (or another value) shortly after.

Read a contact

GET /api/v1/contacts/{contactId} — returns a contact's details in data.

Update a contact

PUT /api/v1/contacts/{contactId} — updates name, email and/or phone. The response includes a message and the updated contact in data.

Delete a contact

DELETE /api/v1/contacts/{contactId} — removes the contact permanently. The response is just a confirmation message.

How to read responses

Responses follow a simple pattern: a single resource comes inside data; when there is an action, a message comes too; and lists are paginated, with data (the items) and meta (current page, total, etc.).

Common errors

• 401 — missing or invalid token. Check the Authorization header.
• 403 — no permission for the resource (for example, a plan without API access).
• 404 — the given list or contact does not exist (or isn't in your account).
• 422 — invalid data. The body includes a message and an errors object pointing to each problematic field.
• 429 — you exceeded the request limit (see below).

Usage limits

• Reads (GET): up to 60 requests per minute (varies by plan).
• Writes (POST/PUT/DELETE): up to 30 requests per minute.
• When you hit the limit, the API responds 429 with the Retry-After header, telling you how many seconds to wait before retrying.

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.
• Handle the 429 status by waiting for the Retry-After time before repeating the request.
• Keep one token per integration and immediately revoke any token that might have leaked.

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