​
Understanding integration contacts

Integration contacts are contacts that are created and managed through the OpenPhone API. They provide a programmatic way to import contact records from external sources into your OpenPhone workspace.

​
Key characteristics

Distinct from app contacts

Integration contacts are separate from contacts created directly in the OpenPhone app, with their own specific behaviors and management flow.

API-first management

These contacts are designed to be managed exclusively through API endpoints, enabling automated contact management and integration with your existing systems. They cannot be modified or deleted within OpenPhone.

​
Important 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.

​
Contact field structure

OpenPhone organizes contact information using two distinct field types. Understanding these is crucial for effective contact management.

Default fields

​
Creating and managing contacts

Follow these steps to effectively create and manage contacts through the API:
1

Retrieve custom fields

First, call the GET /contact-custom-fields endpoint to retrieve your workspace’s custom contact field definitions.
2

Prepare contact data

Structure your contact data according to both default and custom fields:
{
  "defaultFields": {
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumbers": [
      {
        "name": "primary",
        "value": "+1234567890"
      }
    ]
  },
  "customFields": {
    // Include any custom field values here
  }
}
3

Create the contact

Use the POST /contacts endpoint to create the contact and store the returned contact ID for future operations.
4

Manage the contact

Use the saved contact ID with the PATCH /contacts/:id endpoint for any future updates to the contact’s information.
Always validate phone numbers are in E.164 format (+1234567890) before creating or updating contacts to ensure proper functionality.