Contacts

9 endpoints in this family.

List contacts

GET/api/v1/contacts

Returns the people this workspace has talked to, searchable by name, phone number or email. Custom attributes come back alongside, so you can map them into your own records.

Query parameters

qstring
Search by name, phone number or email.
limitinteger
How many to return.
cursorstring
Opaque cursor from the previous page.

Response

A page of contacts, and the attribute definitions that describe their custom fields.

data.itemsContact[]
The contacts.
data.attributesContactAttribute[]
The custom field definitions.
data.nextCursorstring
Pass it as cursor for the next page; null at the end.
data.totalinteger
How many match, on the first page only; null after.

curl https://coplace.io/api/v1/contacts \ -H "Authorization: Bearer $COPLACE_KEY"

Response

200 OK

{ "data": { "items": [ {} ], "attributes": [ {} ], "nextCursor": "…", "total": 0 }}

Create a contact

POST/api/v1/contacts

Key role agent or above

Creates someone before they have written. A contact needs at least one identity — a phone number or an email address — otherwise nothing can ever reach them.

If that identity is already known, the existing contact is returned rather than duplicated.

Body

fullNamestring
Their name, as you want it displayed.
phonestring
Phone number in E.164 form.
emailstring
Email address.
attributesobject
Your custom fields, by key. See GET /contacts/attributes.

Response

The contact.

data.contactContact
data.attributesContactAttribute[]
The custom field definitions.

Refusals

422no_identityNeither a phone number nor an email address was given.

curl -X POST https://coplace.io/api/v1/contacts \  -H "Authorization: Bearer $COPLACE_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone": "+33612345678"  }'

Response

200 OK

{  "data": {    "contact": {      "id": "…",      "displayName": "…",      "locale": "…",      "phone": "…",      "email": "…",      "externalId": "…",      "tags": [],      "attributes": {},      "optInAt": "…",      "optOutAt": "…",      "blocked": true,      "conversationCount": 0,      "lastMessageAt": "…",      "createdAt": "…",      "updatedAt": "…"    },    "attributes": [      {}    ]  }}

Get one contact

GET/api/v1/contacts/{id}

Returns the contact with all their identities and custom attributes.

Path parameters

idstring
The contact id.

Response

The contact, and the attribute definitions describing their custom fields.

data.contactContact
data.attributesContactAttribute[]
The custom field definitions.

curl https://coplace.io/api/v1/contacts/<id> \ -H "Authorization: Bearer $COPLACE_KEY"

Response

200 OK

{  "data": {    "contact": {      "id": "…",      "displayName": "…",      "locale": "…",      "phone": "…",      "email": "…",      "externalId": "…",      "tags": [],      "attributes": {},      "optInAt": "…",      "optOutAt": "…",      "blocked": true,      "conversationCount": 0,      "lastMessageAt": "…",      "createdAt": "…",      "updatedAt": "…"    },    "attributes": [      {}    ]  }}

Update a contact

PATCH/api/v1/contacts/{id}

Key role agent or above

Changes the name or the custom attributes. Fields you leave out keep their value.

Identities — phone numbers and email addresses — are not edited here: they are established by real conversations, and rewriting them would silently merge two people.

Path parameters

idstring
The contact id.

Body

fullNamestring
Their name.
attributesobject
Custom fields to set, by key.

Response

The contact, updated.

data.contactContact
data.attributesContactAttribute[]
The custom field definitions.

curl -X PATCH https://coplace.io/api/v1/contacts/<id> \  -H "Authorization: Bearer $COPLACE_KEY" \  -H "Content-Type: application/json" \  -d '{    "fullName": "…",    "attributes": {}  }'

Response

200 OK

{  "data": {    "contact": {      "id": "…",      "displayName": "…",      "locale": "…",      "phone": "…",      "email": "…",      "externalId": "…",      "tags": [],      "attributes": {},      "optInAt": "…",      "optOutAt": "…",      "blocked": true,      "conversationCount": 0,      "lastMessageAt": "…",      "createdAt": "…",      "updatedAt": "…"    },    "attributes": [      {}    ]  }}

List notes on a contact

GET/api/v1/contacts/{id}/notes

Free-text notes your team or your software wrote about this person, newest first. Notes are never shown to the contact and never read by the collaborator.

Path parameters

idstring
The contact id.

Response

The notes, newest first.

data.itemsContactNote[]
Up to 200 notes, newest first.

curl https://coplace.io/api/v1/contacts/<id>/notes \ -H "Authorization: Bearer $COPLACE_KEY"

Response

200 OK

{ "data": { "items": [ {} ] }}

Add a note to a contact

POST/api/v1/contacts/{id}/notes

Key role agent or above

Writes a free-text note about this person — what your CRM knows, a call summary, a warning for the team. It is signed with your key's label. The contact never sees it.

Path parameters

idstring
The contact id.

Body

bodystringrequired
The note, 1 to 5000 characters.

Response

The note.

data.idstring
The note id.
data.bodystring
The note.
data.authorstring
The person's name or the key's label; null when the author no longer exists.
data.authorKindstring
Who wrote it.
userapi_key
data.createdAtstring
ISO 8601.

curl -X POST https://coplace.io/api/v1/contacts/<id>/notes \  -H "Authorization: Bearer $COPLACE_KEY" \  -H "Content-Type: application/json" \  -d '{    "body": "…"  }'

Response

200 OK

{ "data": { "id": "…", "body": "…", "author": "…", "authorKind": "user", "createdAt": "…" }}

Delete a note

DEL/api/v1/contacts/{id}/notes/{noteId}

Key role agent or above

Deletes a note. Only its author — the same key, or the same person — or an admin key can.

Path parameters

idstring
The contact id.
noteIdstring
The note id.

Response

Confirmation that it is gone.

data.deletedboolean
Always true.

curl -X DELETE https://coplace.io/api/v1/contacts/<id>/notes/<noteId> \ -H "Authorization: Bearer $COPLACE_KEY"

Response

200 OK

{ "data": { "deleted": true }}

List the custom contact fields

GET/api/v1/contacts/attributes

Returns the fields this account defined on its contacts: their key, label and type. Read this before writing attributes on a contact — an unknown key is refused.

These belong to the account, so every workspace of the same client shares them.

Response

The attribute definitions.

data.itemsContactAttribute[]
The definitions.

curl https://coplace.io/api/v1/contacts/attributes \ -H "Authorization: Bearer $COPLACE_KEY"

Response

200 OK

{ "data": { "items": [ {} ] }}

Erase a person, for good

DEL/api/v1/privacy/contacts/{id}

Key role admin or above

Irreversible. Deletes the contact, their identities, their messages and their conversations. Meant for a right-to-erasure request.

What is kept is what carries no personal data: counters, and the record that an erasure happened. The call returns a report of what was removed.

Path parameters

idstring
The contact id.

Response

A report: what was erased, and how much of it.

data.erasedboolean
Always true.
data.removedobject
Counts removed: identities, conversations, messages.
data.emptiedobject
Counts kept for deduplication but emptied of their content.

curl -X DELETE https://coplace.io/api/v1/privacy/contacts/<id> \ -H "Authorization: Bearer $COPLACE_KEY"

Response

200 OK

{ "data": { "erased": true, "removed": {}, "emptied": {} }}