Skip to main content
Esc
Browse docs

Contacts API

Use the Slovio Contacts API to create, update and list contacts: the fields you can send, the JSON you get back, filters and pagination with 1 to 100 per page.

3 min readUpdated

The Contacts API lets your website, CRM or app add people to Slovio and keep them up to date. Send POST /v1/public/api/contact to create a contact, PATCH /v1/public/api/contact/{contactId} to change one, and GET /v1/public/api/contact to list them. Every request needs the x-access-key and Authorization: Bearer headers described in API overview.

Create a contact

http
POST https://api.slovio.ai/v1/public/api/contact
bash
curl -X POST https://api.slovio.ai/v1/public/api/contact \
  -H "x-access-key: $SLOVIO_ACCESS_KEY" \
  -H "Authorization: Bearer $SLOVIO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Rohit",
    "lastName": "Mehta",
    "contact_number": "9876543210",
    "countryCode": "91",
    "email": "rohit@mehtatraders.in",
    "address": "MI Road, Jaipur",
    "optInMessages": true
  }'
Field Rules
firstName Required, at least 1 character.
contact_number Required, at least 10 characters. It must be a valid phone number.
countryCode Optional, for example 91.
lastName, email Optional.
address Optional, up to 500 characters.
optInMessages true if the person agreed to receive messages.
tags Optional list of tag IDs.
source, stage, status, priority Optional. Each is the ID of a value set up in your CRM settings.
customFields Optional list of { "_id": "<custom field ID>", "value": "..." }.
note Optional, up to 2000 characters.

Any field not accepted by the endpoint is rejected with a validation error, so send only the fields you need.

Response

HTTP 200 with the saved contact:

json
{
  "statusCode": "10000",
  "status": 200,
  "message": "Contact created successfully",
  "data": {
    "_id": "66f3b1d2a4c9e80012cd7781",
    "firstName": "Rohit",
    "lastName": "Mehta",
    "contact_number": "9876543210",
    "countryCode": "91",
    "email": "rohit@mehtatraders.in",
    "tags": [],
    "optInMessages": true,
    "blocked": false,
    "customFields": [],
    "createdAt": "2026-10-03T06:12:45.000Z",
    "updatedAt": "2026-10-03T06:12:45.000Z"
  }
}

Keep data._id. It is the contactId you use to update the contact. The contact has more fields than shown here; the ones you didn't set are empty or have their default.

Create errors

HTTP Message
400 Contact Number is not valid
400 Contact already exist

Update a contact

http
PATCH https://api.slovio.ai/v1/public/api/contact/{contactId}

Every field is optional. Send only what changes:

json
{ "email": "accounts@mehtatraders.in", "optInMessages": false }

The response is HTTP 200 with "message": "Contact updated successfully" and the updated contact in data. An unknown ID returns Contact not found.

List contacts

http
GET https://api.slovio.ai/v1/public/api/contact?page=1&limit=25
Query Rules
page 1 to 10,000. Default 1.
limit 1 to 100. Default 25.
search Name or number, up to 200 characters.
tags, source, status, stage, priority, type Filters.
startDate, endDate Created between these dates.
sortBy, sortOrder Sort field, and asc or desc. Newest updated first by default.
json
{
  "statusCode": "10000",
  "status": 200,
  "message": "success",
  "data": {
    "contacts": [
      {
        "_id": "66f3b1d2a4c9e80012cd7781",
        "firstName": "Rohit",
        "lastName": "Mehta",
        "contact_number": "9876543210",
        "countryCode": "91",
        "email": "rohit@mehtatraders.in"
      }
    ],
    "totalPages": 4,
    "totalContacts": 87
  }
}

To read every contact, start at page=1 and keep going until page equals totalPages. Paging deeper than 250,000 contacts is refused with Page is too far for this page size.; use search or filters instead.

Common questions

Why was my request rejected with "Unrecognized key(s) in object"?

You sent a field the endpoint does not accept, for example phone instead of contact_number. Remove it or rename it to one of the fields above.

Can I send tag names instead of tag IDs?

No. tags, source, stage, status and priority take IDs, not names. Create the values in your CRM settings first and use their IDs.

What happens if the contact already exists?

Create returns HTTP 400 Contact already exist. Use update with the contact's ID instead.

How many contacts can I fetch at once?

Up to 100 per page with limit=100. Use page and totalPages to go through the rest.

Stuck, or is something here out of date? Tell the team — we reply within a working day.