Integration contacts
Learn more about working with contacts via the OpenPhone API.
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 includes first 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 as address, boolean, date, multi-select, number, string, and url are supported.
3. Creating a contact
To create a new contact, you can first retrieve your workspace’s custom contact fields by calling the GET /contact-custom-fields endpoint. These custom fields, along with the default fields, can then be used to create new contacts.
Was this page helpful?