Autocomplete contacts
const url = 'https://contacts.work.optidata.cloud/api/contacts/autocomplete?query=ana&limit=50';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/autocomplete?query=ana&limit=50' \ --header 'Authorization: Bearer <token>'Suggestions for a partially typed name, e-mail address or phone number —
built for recipient fields and contact pickers. Matching and ranking are
the same as GET /contacts/search, but the answer is a flat list and
each suggestion’s emails and phones are plain strings, ready to
display.
For accounts whose mail is hosted on the Optiwork mail platform, the list
also includes the caller’s contact groups that match the term. A
group suggestion has the shape of ContactSuggestionFromMail, with
type: groupContact and the members’ addresses in emails. The same
shape is used for every suggestion while the caller’s address book is
being prepared for the first time.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters”What the user has typed so far.
Maximum number of suggestions to return.
Responses
Section titled “ Responses ”Suggestions, best match first.
An address-book contact offered as an autocomplete suggestion.
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.
Relevance, as in GET /contacts/search.
E-mail addresses, the primary one first.
Phone numbers, as entered, the primary one first.
The organizations a person works for.
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.
Name of the person’s first listed employer, for display.
A suggestion that comes from the caller’s mail address book rather than
from Contacts: a contact group, or any entry while the address book is
being prepared for the first time. Its id is a string and cannot be
used with the other Contacts endpoints.
object
The entry’s addresses — for a group, its members’ addresses.
groupContact for a contact group, contact for a saved contact, emailedContacts for an address collected from sent mail.
Examples
[ { "id": 33901, "type": "person", "name": "Ana Souza", "avatar_url": null, "job_title": "Account Manager", "birthdate": null, "website": null, "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": null, "identification_number": null, "zimbra_id": null, "app_id": null, "canonical_contact_id": null, "scope": "user", "app_action": null, "score": 80, "emails": [ "ana.souza@example.com" ], "phones": [ "+5511987654321" ], "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" } } ], "company_name": "Acme Ltda" }, { "id": "8231", "name": "Sales team", "company_name": null, "job_title": null, "emails": [ "ana.souza@example.com", "bruno.lima@example.com" ], "phones": [], "notes": null, "type": "groupContact" }]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." ] }}