List contacts
const url = 'https://contacts.work.optidata.cloud/api/contacts?limit=50&filters%5Bid%5D%5B%5D=33899&filters%5Bid%5D%5B%5D=33900';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://contacts.work.optidata.cloud/api/contacts?limit=50&filters%5Bid%5D%5B%5D=33899&filters%5Bid%5D%5B%5D=33900' \ --header 'Authorization: Bearer <token>'Returns the caller’s contacts, each with its e-mail addresses, phone
numbers and employers. The list is not paginated: limit caps how many
come back (50 by default, at most 1000).
Pass filters[id][] one or more times to fetch specific contacts by id —
the usual way to refresh a handful of contacts you already know. Ids that
do not exist, or that belong to someone else, are silently left out.
No particular order is guaranteed. Use GET /contacts/search when you
need results ranked against a term.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters”Maximum number of contacts to return.
Only return the contacts with these ids. Repeat the parameter for each id.
Responses
Section titled “ Responses ”The caller’s contacts.
A contact with its e-mail addresses, phone numbers and employers.
object
Contact id.
What a contact represents. person and organization are the everyday
kinds; the others identify mail-platform entries kept in the address
book (distribution_list, group, resource) and secondary addresses
that point to another contact (alias).
Display name — a person’s full name or an organization’s name.
URL of the contact’s picture, when one was set.
A person’s job title. Always null for an organization.
Birth date, at midnight UTC.
Free-form notes.
Additional user-defined fields, as name/value pairs.
Postal address, as a single line of text.
A tax or company registration number.
Who a contact belongs to. user is a personal address-book entry;
company is an entry shared across the company.
Identifier of the company the contact was created in.
Numeric id of the user who owns the contact — always the caller.
UUID of the user who owns the contact — always the caller.
Id of the matching entry in the mail platform’s address book, when the contact was imported from it.
Id of the Optiwork module that added the contact automatically (for example, Calendar when you invite someone new), or null when it was added by hand or imported.
What, in that module, caused the contact to be added.
For an alias, the id of the contact it points to.
Always null — contacts in the trash are not returned.
E-mail addresses, the primary one first.
One e-mail address or phone number of a contact.
object
The address or number, as entered.
The value in canonical form — a lower-cased e-mail address, or an
E.164 phone number. null when a phone number could not be parsed.
Whether this is the contact’s preferred address or number of its kind.
Who a contact belongs to. user is a personal address-book entry;
company is an entry shared across the company.
UUID of the owner for a personal (user) contact; null for a company-wide one.
Id of the contact this method belongs to.
Internal type tag of the owning record. Not meaningful to API clients.
Internal search index of the value. Not meaningful to API clients.
Phone numbers, the primary one first.
One e-mail address or phone number of a contact.
object
The address or number, as entered.
The value in canonical form — a lower-cased e-mail address, or an
E.164 phone number. null when a phone number could not be parsed.
Whether this is the contact’s preferred address or number of its kind.
Who a contact belongs to. user is a personal address-book entry;
company is an entry shared across the company.
UUID of the owner for a personal (user) contact; null for a company-wide one.
Id of the contact this method belongs to.
Internal type tag of the owning record. Not meaningful to API clients.
Internal search index of the value. Not meaningful to API clients.
The organizations a person works for. Always empty for an organization.
An employer of a person contact.
object
Contact id.
What a contact represents. person and organization are the everyday
kinds; the others identify mail-platform entries kept in the address
book (distribution_list, group, resource) and secondary addresses
that point to another contact (alias).
Display name — a person’s full name or an organization’s name.
URL of the contact’s picture, when one was set.
A person’s job title. Always null for an organization.
Birth date, at midnight UTC.
Free-form notes.
Additional user-defined fields, as name/value pairs.
Postal address, as a single line of text.
A tax or company registration number.
Who a contact belongs to. user is a personal address-book entry;
company is an entry shared across the company.
Identifier of the company the contact was created in.
Numeric id of the user who owns the contact — always the caller.
UUID of the user who owns the contact — always the caller.
Id of the matching entry in the mail platform’s address book, when the contact was imported from it.
Id of the Optiwork module that added the contact automatically (for example, Calendar when you invite someone new), or null when it was added by hand or imported.
What, in that module, caused the contact to be added.
For an alias, the id of the contact it points to.
Always null — contacts in the trash are not returned.
The link between the person and this organization.
object
Id of the person.
Id of the organization.
Examples
[ { "id": 33901, "type": "person", "name": "Ana Souza", "avatar_url": null, "job_title": "Account Manager", "birthdate": "1990-04-12T00:00:00.000000Z", "website": null, "notes": "Met at the 2026 partner summit.", "cuid": "7f3c2a10-5b8e-4d21-9c6a-0e4f1b2d3c4a", "created_by_id": 5, "created_by_uuid": "2d9e8f70-1a3b-4c5d-8e9f-a0b1c2d3e4f5", "created_at": "2026-10-15T20:31:01.000000Z", "updated_at": "2026-10-15T20:31:01.000000Z", "deleted_at": null, "custom_fields": null, "address": null, "identification_number": null, "zimbra_id": null, "app_id": null, "canonical_contact_id": null, "scope": "user", "app_action": null, "emails": [ { "id": 1627, "contactable_type": "App\\Models\\Contacts\\Contact", "contactable_id": 33901, "type": "email", "value": "ana.souza@example.com", "is_primary": true, "created_at": "2026-10-15T20:31:01.000000Z", "updated_at": "2026-10-15T20:31:01.000000Z", "value_normalized": "ana.souza@example.com", "scope": "user", "owner_uuid": "2d9e8f70-1a3b-4c5d-8e9f-a0b1c2d3e4f5", "value_fts": "'ana.souza@example.com':1" } ], "phones": [ { "id": 1628, "contactable_type": "App\\Models\\Contacts\\Contact", "contactable_id": 33901, "type": "phone", "value": "+55 11 98765-4321", "is_primary": true, "created_at": "2026-10-15T20:31:01.000000Z", "updated_at": "2026-10-15T20:31:01.000000Z", "value_normalized": "+5511987654321", "scope": "user", "owner_uuid": "2d9e8f70-1a3b-4c5d-8e9f-a0b1c2d3e4f5", "value_fts": "'+55':1 '11':2 '98765':3 '4321':4" } ], "companies": [ { "id": 33910, "type": "organization", "name": "Acme Ltda", "avatar_url": null, "job_title": null, "birthdate": null, "website": "https://acme.example.com", "notes": null, "cuid": "7f3c2a10-5b8e-4d21-9c6a-0e4f1b2d3c4a", "created_by_id": 5, "created_by_uuid": "2d9e8f70-1a3b-4c5d-8e9f-a0b1c2d3e4f5", "created_at": "2026-10-15T20:31:01.000000Z", "updated_at": "2026-10-15T20:31:01.000000Z", "deleted_at": null, "custom_fields": null, "address": "Av. Paulista, 1000 — São Paulo, SP", "identification_number": null, "zimbra_id": null, "app_id": null, "canonical_contact_id": null, "scope": "user", "app_action": null, "pivot": { "contact_id": 33901, "related_contact_id": 33910, "relation_type": "employee" } } ] }, { "id": 33910, "type": "organization", "name": "Acme Ltda", "avatar_url": null, "job_title": null, "birthdate": null, "website": "https://acme.example.com", "notes": null, "cuid": "7f3c2a10-5b8e-4d21-9c6a-0e4f1b2d3c4a", "created_by_id": 5, "created_by_uuid": "2d9e8f70-1a3b-4c5d-8e9f-a0b1c2d3e4f5", "created_at": "2026-10-15T20:31:01.000000Z", "updated_at": "2026-10-15T20:31:01.000000Z", "deleted_at": null, "custom_fields": null, "address": "Av. Paulista, 1000 — São Paulo, SP", "identification_number": null, "zimbra_id": null, "app_id": null, "canonical_contact_id": null, "scope": "user", "app_action": null, "emails": [], "phones": [], "companies": [] }]No authentication key was sent.
Authentication failures use an error key rather than message.
object
Examples
No bearer token sent
{ "error": "JWT passport exception: Missing bearer token in request"}The authentication key is expired or not recognised. Get a fresh one and retry.
Authentication failures use an error key rather than message.
object
Examples
{ "error": "JWT passport expired: Passport expired"}The query string failed validation.
object
The first validation message.
Validation messages keyed by field name.
object
Examples
Search term missing
{ "message": "The search query field is required.", "errors": { "query": [ "The search query field is required." ] }}Limit out of range
{ "message": "The limit field must be at least 1.", "errors": { "limit": [ "The limit field must be at least 1." ] }}