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.
Create a contact
Section titled “Create a contact”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.
-
Build the request body. Send only the fields you want to set.
Field Type Notes platformstring telegram(default) ortwitter.namestring Display name. usernamestring Handle; a leading @is removed.phonestring Phone number. emailstring Email address. companystring Company name. externalIdstring The contact’s id in your own system. Must be unique in the workspace. country,citystring Location. notesstring Free-text notes. stagestring novalue,lead,conversation,proposal,negotiation,wonorlost.pipelineStageIdinteger A column on one of your pipeline boards. leadScoreinteger Lead score. tagsstring[] Tag names. Tags that do not exist yet are created. -
Send the request. Add an
Idempotency-Keyheader 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"}'const res = await fetch("https://api.pinlyx.com/v1/contacts", {method: "POST",headers: {Authorization: "Bearer csk_live_...","Content-Type": "application/json","Idempotency-Key": "signup-88213",},body: JSON.stringify({name: "Ada Lovelace",username: "adalovelace",externalId: "cust-88213",notes: "Met at conference",}),});const contact = await res.json();console.log(contact.Id);import requestsres = requests.post("https://api.pinlyx.com/v1/contacts",headers={"Authorization": "Bearer csk_live_...","Idempotency-Key": "signup-88213",},json={"name": "Ada Lovelace","username": "adalovelace","externalId": "cust-88213","notes": "Met at conference",},)contact = res.json()print(contact["Id"]) -
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.
List and search contacts
Section titled “List and search contacts”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.
Query parameters
Section titled “Query parameters”| Param | Type | Notes |
|---|---|---|
limit | integer | Page size, 1 to 100. Default 25. |
after | integer | Cursor from the previous page’s nextCursor. Leave it out for the first page. |
order | string | asc walks oldest first, the right order for a full sync. Newest first by default. |
q | string | Case-insensitive search across name, username, phone, email, company and externalId. |
platform | string | Filter by platform, for example telegram or twitter. |
externalId | string | Exact match on your own id. |
email | string | Exact, case-insensitive match on email. |
updatedSince | string | Only contacts created or changed at or after this UTC time. |
includeInactive | boolean | Include archived contacts. Default false. |
curl "https://api.pinlyx.com/v1/contacts?limit=10&q=ada" \ -H "Authorization: Bearer csk_live_..."const params = new URLSearchParams({ limit: "10", q: "ada" });
const res = await fetch(`https://api.pinlyx.com/v1/contacts?${params}`, { headers: { Authorization: "Bearer csk_live_..." },});
const page = await res.json();console.log(page.items.length, page.nextCursor, page.hasMore);import requests
res = requests.get( "https://api.pinlyx.com/v1/contacts", headers={"Authorization": "Bearer csk_live_..."}, params={"limit": 10, "q": "ada"},)
page = res.json()print(len(page["items"]), page["nextCursor"], page["hasMore"])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.
Page through everything
Section titled “Page through everything”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);import requests
after = Noneall_contacts = []
while True: params = {"limit": 100, "order": "asc"} if after is not None: params["after"] = after
res = requests.get( "https://api.pinlyx.com/v1/contacts", headers={"Authorization": "Bearer csk_live_..."}, params=params, ) page = res.json()
all_contacts.extend(page["items"]) after = page["nextCursor"] if after is None: breakFetch a single contact
Section titled “Fetch a single contact”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.
curl https://api.pinlyx.com/v1/contacts/101 \ -H "Authorization: Bearer csk_live_..."