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": "[email protected]",
      "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": "[email protected]", "phone": "+15551234567" }'

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

{
  "message": "Contact created successfully.",
  "data": {
    "id": 123,
    "name": "John Smith",
    "email": "[email protected]",
    "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.