Skip to content
CognizyCognizyHelp
Sign in
In this area

Contacts

List contacts and manage their tags.

List or search contacts

get/v1/public/contacts

Returns a paginated list of contacts in your organization. Use query for free-text search across name/email/phone.

Parameters

limitnumberoptional· query
Range 1–100, default 25
pagenumberoptional· query
hasPhonebooleanoptional· query
hasEmailbooleanoptional· query
tagIdstringoptional· query
Filter to contacts that have this tag. Repeat to OR multiple.
querystringoptional· query
Free-text search across name/email/phone

Responses

  • 200

Examples

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/contacts" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Get a contact by id

get/v1/public/contacts/{id}

Returns the full contact record including recent conversations, deals, appointments, tags, and custom fields.

Parameters

idstringrequired· path
Contact ID

Responses

  • 200Contact record returned
  • 404Contact not found

Examples

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/contacts/<id>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Add a tag to a contact

post/v1/public/contacts/{id}/tags

Accepts Idempotency-Key

Attaches an existing tag to a contact. Idempotent — calling twice with the same pair is a no-op (no error). Same effect as the in-app dashboard tagging.

Parameters

idstringrequired· path
Contact ID

Body (JSON)required

tagIdstringrequired
Tag ID to attach to the contact

Responses

  • 204Tag attached (or already attached — idempotent)
  • 400Missing or invalid `tagId`
  • 404Contact or tag not found

Examples

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/contacts/<id>/tags" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "tagId": "tag_123"
}'

Remove a tag from a contact

delete/v1/public/contacts/{id}/tags/{tagId}

Detaches a tag from a contact. Returns 204 even if the tag wasn't attached (the postcondition holds regardless).

Parameters

idstringrequired· path
Contact ID
tagIdstringrequired· path
Tag ID to detach

Responses

  • 204Tag detached (or was not attached — idempotent)
  • 404Contact or tag not found

Examples

bash
curl -X DELETE "https://api.cognizy.ai/api/v1/public/contacts/<id>/tags/<tagId>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Full reference