Contatos — API Zyron Connect Suite

Getting started

Module

Contacts

Create, inspect and move contacts inside the CRM funnel.

GET/contacts/contacts GET/contacts/:id/contacts/:id POST/contacts/contacts PATCH/contacts/:id/contacts/:id

GET/contactsScope: readOfficial + Basic

List contacts from the authenticated account.

Use it to feed external CRMs, sync databases and fetch contacts by stage.

Path parameters

No additional parameters.

Query parameters

Field	Type	Description
`stage_id`optional	uuid	Filters contacts by a pipeline stage.
`connection_id`optional	uuid	Filters by the WhatsApp connection that owns the identity.
`phone`optional	string	Filters by phone with country code (digits only).
`username`optional	string	Filters by the external identifier stored on the contact.
`business_scoped_user_id`optional	string	Filters by the Meta BSUID identity.
`parent_business_scoped_user_id`optional	string	Filters by the Meta parent BSUID.
`limit`optional	number	Records per page. Default 50; maximum 200 on most list endpoints.
`offset`optional	number	Initial page index. Use pagination.next_offset to fetch the next page.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/contacts?limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	List returned with pagination.
401	Missing or invalid key.
403	Key lacks read scope.

Response example

{
  "data": [
    {
      "id": "<CONTACT_ID>",
      "name": "Maria Silva",
      "phone": "5511999998888",
      "username": "maria",
      "stage_id": "<STAGE_ID>",
      "created_at": "2026-06-15T12:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 134,
    "next_offset": 20
  }
}

GET/contacts/:idScope: readOfficial + Basic

Fetch one contact with journey and sales.

Returns contact data, Signal source sessions and sales related to that contact's conversations.

Path parameters

Field	Type	Description
`id`required	uuid	Contact ID.

Query parameters

No additional parameters.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/contacts/<CONTACT_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Contact found.
404	Contact not found in this account.

Response example

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Maria Silva",
    "phone": "5511999998888",
    "username": "maria",
    "stage_id": "<STAGE_ID>",
    "sessions": [
      {
        "channel": "ctwa",
        "utm_source": null,
        "utm_campaign": null,
        "ad_id": "23800000000000000",
        "ad_source_type": "ad",
        "ad_headline": "Fale com a gente",
        "ad_name": "Criativo vídeo depoimento",
        "adset_id": "23700000000000000",
        "adset_name": "Lookalike 1% — 25-45",
        "campaign_id": "23600000000000000",
        "campaign_name": "Leads — Julho",
        "landing_url": "https://sua-pagina.com/oferta"
      }
    ],
    "sales": [
      {
        "id": "91c9fd84-b47f-44ee-9b5e-4e93fc35b912",
        "status": "paid",
        "gross_cents": 19700,
        "currency": "BRL",
        "product_name": "Produto principal"
      }
    ]
  }
}

POST/contactsScope: writeOfficial + Basic

Create or update a contact by identity.

Send at least one identity: phone, username, business_scoped_user_id or parent_business_scoped_user_id. The phone is normalized to digits only. Meta identities require connection_id. If the identity already exists, the API updates the sent fields.

Path parameters

No additional parameters.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`phone`optional	string	Phone with country code, digits only. Required when no other identity is sent.
`connection_id`optional	uuid	Connection that owns the identity. Required with username, BSUID or parent BSUID.
`name`optional	string	CRM display name, up to 120 characters.
`username`optional	string	External identifier or social username.
`business_scoped_user_id`optional	string	BSUID received from Meta.
`parent_business_scoped_user_id`optional	string	Parent BSUID received from Meta.
`stage_id`optional	uuid	Initial pipeline stage. Must belong to the account.

Ready examples

curl -X POST "https://connect.zyronstack.com/api/v1/contacts" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "phone": "5511999998888",
  "name": "Joao Silva",
  "username": "joao",
  "stage_id": "<STAGE_ID>"
}'

Responses

201	Contact created.
200	Existing contact updated.
422	Missing phone or invalid stage_id.

Response example

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Joao Silva",
    "phone": "5511999998888",
    "username": "joao",
    "stage_id": "<STAGE_ID>",
    "created_at": "2026-06-15T12:30:00.000Z"
  },
  "created": true
}

PATCH/contacts/:idScope: writeOfficial + Basic

Update data or move a contact to another stage.

Send only the fields you want to change. stage_id is validated against the account stages. WhatsApp identities (phone, BSUID, parent BSUID) can also be completed here.

Path parameters

Field	Type	Description
`id`required	uuid	Contact ID.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`name`optional	string	New contact name.
`phone`optional	string	New phone with country code (digits only).
`username`optional	string	New external identifier.
`business_scoped_user_id`optional	string	Meta BSUID.
`parent_business_scoped_user_id`optional	string	Meta parent BSUID.
`stage_id`optional	uuid	New pipeline stage.

Ready examples

curl -X PATCH "https://connect.zyronstack.com/api/v1/contacts/<CONTACT_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "stage_id": "<STAGE_ID>",
  "name": "Joao Silva"
}'

Responses

200	Contact updated.
404	Contact not found.
422	stage_id does not belong to the account.

Response example

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Joao Silva",
    "phone": "5511999998888",
    "username": "joao",
    "stage_id": "<STAGE_ID>",
    "created_at": "2026-06-15T12:30:00.000Z"
  }
}