Contacts
Address book entries. Business mail only.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
List contacts
GET /v1/contacts · scope mailboxes:read
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
q |
query | string | Free-text search across name, email, company |
type |
query | string | Filter by contact_type |
department |
query | string | Filter by department |
status |
query | string | Filter by status |
source |
query | string | Filter by source |
Response 200
List of contacts
| Field | Type | Notes |
|---|---|---|
data |
array of Contact |
Errors: 401, 403
Create a contact
POST /v1/contacts · scope mailboxes:write
Request body
| Field | Type | Notes |
|---|---|---|
name |
string | Required. |
email |
string | Required. |
phone |
string | |
company |
string | |
notes |
string | |
contact_type |
string (internal, external) |
|
department |
string | |
role |
string |
Response 201
Contact created
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
name |
string | Required. |
email |
string | Required. |
phone |
string | |
company |
string | |
notes |
string | |
contact_type |
string (internal, external) |
Required. |
source |
string | |
department |
string | |
role |
string | |
status |
string | Required. |
created_at |
string | Required. |
updated_at |
string | Required. |
external_system |
string | The system that owns this contact’s external id. Absent on contacts made by hand. |
external_id |
string | The contact’s id in external_system. Absent on contacts made by hand. |
Errors: 400, 401, 403
Create or update up to 500 contacts by their ids in another system
PUT /v1/contacts/external/{system} · scope contacts:write
For a sync. Each row stands alone: a bad row is reported in results with its index and the rest are stored, so the response is 200 whenever the request itself is well formed. Read failed and results. Two rows with the same external_id in one request are refused (the later one), because which is current cannot be known. Rerunning the same payload updates rather than duplicates.
Request body
| Field | Type | Notes |
|---|---|---|
contacts |
array of object | Required. |
Response 200
Per-row results
| Field | Type | Notes |
|---|---|---|
created |
integer | Required. |
updated |
integer | Required. |
failed |
integer | Required. |
results |
array of object | Required. |
Errors: 400, 401, 403
Get a contact by its id in another system
GET /v1/contacts/external/{system}/{external_id} · scope contacts:read
Response 200
Contact details
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
name |
string | Required. |
email |
string | Required. |
phone |
string | |
company |
string | |
notes |
string | |
contact_type |
string (internal, external) |
Required. |
source |
string | |
department |
string | |
role |
string | |
status |
string | Required. |
created_at |
string | Required. |
updated_at |
string | Required. |
external_system |
string | The system that owns this contact’s external id. Absent on contacts made by hand. |
external_id |
string | The contact’s id in external_system. Absent on contacts made by hand. |
Errors: 401, 403, 404
Create or update a contact by its id in another system
PUT /v1/contacts/external/{system}/{external_id} · scope contacts:write
Idempotent: the path is the identity, so sending the same request twice cannot create a second contact, and you never need to store our id. Returns 201 when the contact was created and 200 when it already existed. The body is the full representation: a field you leave out is cleared. Email is an ordinary attribute, not a key, so changing it updates the same contact. mailboxes:write is also accepted.
Request body
| Field | Type | Notes |
|---|---|---|
email |
string | Required. |
name |
string | Defaults to the email address when empty. |
phone |
string | |
company |
string | |
notes |
string | |
contact_type |
string (internal, external) |
|
department |
string | |
role |
string | |
status |
string (active, disabled) |
Response 200
The contact already existed and was updated
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
name |
string | Required. |
email |
string | Required. |
phone |
string | |
company |
string | |
notes |
string | |
contact_type |
string (internal, external) |
Required. |
source |
string | |
department |
string | |
role |
string | |
status |
string | Required. |
created_at |
string | Required. |
updated_at |
string | Required. |
external_system |
string | The system that owns this contact’s external id. Absent on contacts made by hand. |
external_id |
string | The contact’s id in external_system. Absent on contacts made by hand. |
Errors: 400, 401, 403
Delete a contact by its id in another system
DELETE /v1/contacts/external/{system}/{external_id} · scope contacts:write
Response 204
Contact deleted
Errors: 401, 403, 404
Get a contact
GET /v1/contacts/{id} · scope mailboxes:read
Response 200
Contact details
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
name |
string | Required. |
email |
string | Required. |
phone |
string | |
company |
string | |
notes |
string | |
contact_type |
string (internal, external) |
Required. |
source |
string | |
department |
string | |
role |
string | |
status |
string | Required. |
created_at |
string | Required. |
updated_at |
string | Required. |
external_system |
string | The system that owns this contact’s external id. Absent on contacts made by hand. |
external_id |
string | The contact’s id in external_system. Absent on contacts made by hand. |
Errors: 401, 403, 404
Update a contact
PATCH /v1/contacts/{id} · scope mailboxes:write
Request body
| Field | Type | Notes |
|---|---|---|
name |
string | |
email |
string | |
phone |
string | |
company |
string | |
notes |
string | |
contact_type |
string (internal, external) |
|
department |
string | |
role |
string | |
status |
string (active, disabled) |
Response 200
Contact updated
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
name |
string | Required. |
email |
string | Required. |
phone |
string | |
company |
string | |
notes |
string | |
contact_type |
string (internal, external) |
Required. |
source |
string | |
department |
string | |
role |
string | |
status |
string | Required. |
created_at |
string | Required. |
updated_at |
string | Required. |
external_system |
string | The system that owns this contact’s external id. Absent on contacts made by hand. |
external_id |
string | The contact’s id in external_system. Absent on contacts made by hand. |
Errors: 400, 401, 403, 404
Delete a contact
DELETE /v1/contacts/{id} · scope mailboxes:write
Response 204
Contact deleted
Errors: 401, 403, 404
Get lists a contact belongs to
GET /v1/contacts/{id}/lists · scope mailboxes:read
Response 200
Lists containing this contact
| Field | Type | Notes |
|---|---|---|
data |
array of object |
Errors: 401, 403, 404