Skip to main content
GET
/
v1
/
contacts
List contacts
curl --request GET \
  --url https://api.openphone.com/v1/contacts \
  --header 'Authorization: <api-key>'
{
  "data": [
    {
      "id": "664d0db69fcac7cf2e6ec",
      "externalId": "664d0db69fcac7cf2e6ec",
      "source": "public-api",
      "sourceUrl": "https://openphone.co/contacts/664d0db69fcac7cf2e6ec",
      "defaultFields": {
        "company": "OpenPhone",
        "emails": [
          {
            "name": "company email",
            "value": "abc@example.com",
            "id": "acb123"
          }
        ],
        "firstName": "John",
        "lastName": "Doe",
        "phoneNumbers": [
          {
            "name": "company phone",
            "value": "+12345678901",
            "id": "acb123"
          }
        ],
        "role": "Sales"
      },
      "customFields": [
        {
          "name": "Inbound Lead",
          "key": "inbound-lead",
          "id": "66d0d87d534de8fd1c433cec3",
          "type": "multi-select",
          "value": [
            "<string>"
          ]
        }
      ],
      "createdAt": "2022-01-01T00:00:00Z",
      "updatedAt": "2022-01-01T00:00:00Z",
      "createdByUserId": "US123abc"
    }
  ],
  "totalItems": 123,
  "nextPageToken": "<string>"
}

Authorizations

​
Authorization
string
header
required

Query Parameters

​
externalIds
string[]

Optional list of unique identifiers from an external system used to retrieve specific contacts. When provided, the result set is limited to contacts associated with the provided externalIds. These IDs must match those supplied during contact creation via the "Create Contacts" endpoint. When omitted, returns all contacts for the organization. Use this parameter to cross-reference and fetch contacts linked to external systems.

A unique identifier from an external system that can optionally be supplied when creating a contact. This ID is used to associate the contact with records in other systems and is required for retrieving the contact later via the "List Contacts" endpoint. Ensure the externalId is unique and consistent across systems for accurate cross-referencing.

​
sources
string[]

Indicates how the contact was created or where it originated from.

​
maxResults
integer
default:10
required

Maximum number of results to return per page.

Required range: 1 <= x <= 50
​
pageToken
string

Response

Success

​
data
object[]
required
​
totalItems
integer
required

Total number of items available. ⚠️ Note: totalItems is not accurately returning the total number of items that can be paginated. We are working on fixing this issue.

​
nextPageToken
string | null
required
⌘I