​
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.
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 the GET /contact-custom-fields endpoint. These custom fields, along with the default fields, can then be used to create new contacts.