Skip to content

Sync contacts

Contacts are the core record in Pinlyx: every person you talk to on any channel. This guide creates a contact, then lists and searches contacts with cursor pagination, the shape you need to keep another system in sync.

All requests go to https://api.pinlyx.com with your API key as a bearer token. If you have no key yet, start with the API quickstart.

Send a POST to /v1/contacts. At least one of name, username, phone, email or externalId is required. platform is telegram when you leave it out.

  1. Build the request body. Send only the fields you want to set.

    FieldTypeNotes
    platformstringtelegram (default) or twitter.
    namestringDisplay name.
    usernamestringHandle; a leading @ is removed.
    phonestringPhone number.
    emailstringEmail address.
    companystringCompany name.
    externalIdstringThe contact’s id in your own system. Must be unique in the workspace.
    country, citystringLocation.
    notesstringFree-text notes.
    stagestringnovalue, lead, conversation, proposal, negotiation, won or lost.
    pipelineStageIdintegerA column on one of your pipeline boards.
    leadScoreintegerLead score.
    tagsstring[]Tag names. Tags that do not exist yet are created.
  2. Send the request. Add an Idempotency-Key header so a retry after a timeout cannot create the contact twice.

    Terminal window
    curl -X POST https://api.pinlyx.com/v1/contacts \
    -H "Authorization: Bearer csk_live_..." \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: signup-88213" \
    -d '{
    "name": "Ada Lovelace",
    "username": "adalovelace",
    "externalId": "cust-88213",
    "notes": "Met at conference"
    }'
  3. Read the response. A successful create returns 201 Created with the full contact. Contact records use PascalCase field names.

    {
    "Id": 101,
    "Platform": "telegram",
    "Name": "Ada Lovelace",
    "Username": "adalovelace",
    "Phone": null,
    "Email": null,
    "Company": null,
    "ExternalId": "cust-88213",
    "Country": null,
    "City": null,
    "Notes": "Met at conference",
    "Stage": "NoValue",
    "PipelineId": 3,
    "PipelineStageId": 11,
    "LeadScore": null,
    "LeadScoreIsAi": false,
    "AssignedToUserId": null,
    "OwnerUserId": 42,
    "Source": "OutboundMessage",
    "IsArchived": false,
    "CreatedAt": "2026-03-01T10:00:00Z",
    "UpdatedAt": "2026-03-01T10:00:00Z",
    "LastMessageAt": null,
    "HasUnreadMessages": false,
    "CustomFields": null,
    "Tags": []
    }

A 400 means no identifier was given or a field has an invalid value, such as an unknown platform. A 409 means another contact in the workspace already has this externalId. To create or update many contacts in one call, keyed on externalId, use POST /v1/contacts/batch.

Send a GET to /v1/contacts. The list is cursor-paginated: each page returns nextCursor, which you pass back as after to get the next page.

ParamTypeNotes
limitintegerPage size, 1 to 100. Default 25.
afterintegerCursor from the previous page’s nextCursor. Leave it out for the first page.
orderstringasc walks oldest first, the right order for a full sync. Newest first by default.
qstringCase-insensitive search across name, username, phone, email, company and externalId.
platformstringFilter by platform, for example telegram or twitter.
externalIdstringExact match on your own id.
emailstringExact, case-insensitive match on email.
updatedSincestringOnly contacts created or changed at or after this UTC time.
includeInactivebooleanInclude archived contacts. Default false.
Terminal window
curl "https://api.pinlyx.com/v1/contacts?limit=10&q=ada" \
-H "Authorization: Bearer csk_live_..."

The page wrapper uses camelCase (items, nextCursor, hasMore); each item is a contact record like the one above. nextCursor is null when hasMore is false:

{
"items": [
{ "Id": 101, "Platform": "telegram", "Name": "Ada Lovelace", "Username": "adalovelace", "Tags": null }
],
"nextCursor": null,
"hasMore": false
}

List items carry Tags: null. Fetch a single contact to get its tags.

Request pages with after=nextCursor until hasMore is false. Use order=asc for a stable walk, and add updatedSince on later runs to fetch only what changed.

let after;
const all = [];
do {
const params = new URLSearchParams({ limit: "100", order: "asc" });
if (after != null) params.set("after", String(after));
const res = await fetch(`https://api.pinlyx.com/v1/contacts?${params}`, {
headers: { Authorization: "Bearer csk_live_..." },
});
const page = await res.json();
all.push(...page.items);
after = page.nextCursor;
} while (after != null);

GET /v1/contacts/{id} returns one contact, including its Tags array (Id, Name, Color). A 404 means the contact does not exist or is outside your workspace.

Terminal window
curl https://api.pinlyx.com/v1/contacts/101 \
-H "Authorization: Bearer csk_live_..."