POST
/
v1
/
contacts
curl --request POST \
  --url https://api.openphone.com/v1/contacts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "defaultFields": {
    "company": "OpenPhone",
    "emails": [
      {
        "name": "company email",
        "value": "[email protected]"
      }
    ],
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumbers": [
      {
        "name": "company phone",
        "value": "+12345678901"
      }
    ],
    "role": "Sales"
  },
  "customFields": [
    {
      "key": "inbound-lead",
      "value": [
        "<string>"
      ]
    }
  ],
  "createdByUserId": "US123abc",
  "source": "public-api",
  "sourceUrl": "https://openphone.co/contacts/664d0db69fcac7cf2e6ec",
  "externalId": "664d0db69fcac7cf2e6ec"
}'
{
  "data": {
    "id": "664d0db69fcac7cf2e6ec",
    "externalId": "664d0db69fcac7cf2e6ec",
    "source": "public-api",
    "sourceUrl": "https://openphone.co/contacts/664d0db69fcac7cf2e6ec",
    "defaultFields": {
      "company": "OpenPhone",
      "emails": [
        {
          "name": "company email",
          "value": "[email protected]",
          "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"
  }
}

Authorizations

​
Authorization
string
header
required

Body

application/json
​
defaultFields
object
required
​
customFields
object[]
​
createdByUserId
string

The unique identifier of the user who created the contact.

Example:

"US123abc"

​
source
string
default:public-api

The contact's source. Defaults to null for contacts created in the UI. Defaults to public-api for contacts created via the public API. Cannot be one of the following reserved words: openphone, device, csv, zapier, google-people, other or start with one of the following reserved prefixes: openphone, csv.

Required string length: 1 - 72
Example:

"public-api"

​
sourceUrl
string

A link to the contact in the source system.

Required string length: 1 - 200
Example:

"https://openphone.co/contacts/664d0db69fcac7cf2e6ec"

​
externalId
string | null

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.

Required string length: 1 - 75
Example:

"664d0db69fcac7cf2e6ec"

Response

201
application/json
Success
​
data
object
required

Was this page helpful?