Overview
This guide provides an overview of the key concepts, features, and best practices for effectively using the OpenPhone Contacts API.What are integration contacts?
Integration contacts are contacts created through the OpenPhone API, distinct from contacts created directly in the OpenPhone app. Please be aware of the following key behaviors and limitations.Preserving contact IDs
When you create an integration contact using the
POST /contacts endpoint, it’s essential to save the id returned in the response. This id will be required for all future operations involving the contact.Visibility in the OpenPhone app
After creating an integration contact, it will only appear in the OpenPhone app—whether in the conversation list, contact list, or search results—if there’s an associated conversation with a matching phone number.
Read-only status
At present, integration contacts are read-only within the OpenPhone app. To make any updates or changes to an integration contact, you will need to use the
PATCH /contacts/:id endpoint.Understanding Contact Field Data
Contact information in OpenPhone is stored in two types of fields.1. Default fields
These are predefined fields that exist for every contact and always have the same properties. This includesfirst name, last name,role,company,emails, and phone numbers.
2. Custom fields
Custom fields are user-defined properties created within the OpenPhone app. Data types such asaddress, boolean, date, multi-select, number, string, and url are supported.
Managing custom fields: If you need to modify custom contact fields, this must be done within the OpenPhone app. The current API functionality does not offer the ability to create or edit custom fields directly.
3. Creating a contact
To create a new contact, you can first retrieve your workspace’s custom contact fields by calling theGET /contact-custom-fields endpoint. These custom fields, along with the default fields, can then be used to create new contacts.