Create a contact

External contacts are Project Blue's native contact store for accounts without a connected CRM. They render in the Project Blue app's contact list and details panel.

POST/create-external-contactBearer token

You can create them explicitly with the endpoints below, or implicitly by passing firstName, lastName, email, and customFields on /send-api-message — those fields persist on the auto-created contact for the recipient.

For accounts without a connected CRM

If HighLevel or HubSpot is connected, contacts live in your CRM instead (see CRM integration). External contacts apply to external/API-source accounts.

Required: phone only (plus Authorization: Bearer <api key>). Optional: firstName, lastName, email, customFields.

customFields is a JSON object of key/value pairs, max 10,000 characters when stringified. Omit it entirely if you have none. Same phone for the same API key is an upsert (fills blank names, overwrites email, shallow-merges customFields).

Upserts do not behave like updates

When the phone number already exists this endpoint merges rather than replaces, and the rules differ per field:

firstName and lastName are only filled in when the stored value is empty. Sending a new name for a contact that already has one is silently discarded.
email overwrites whenever you send a non-empty value.
customFields is shallow-merged here — the opposite of update, which replaces the whole object. Sending {} changes nothing.

The response is the contact as it was before the merge, so a discarded name is not visible in it. Read the contact back if you need to confirm. The same merge runs when /send-api-message auto-creates a contact.

Request body

phonestringRequired

The only required field besides Authorization. E.164 like +12345678901.

firstNamestring

The contact's first name. On upsert, filled in only when the stored value is blank.

lastNamestring

The contact's last name. On upsert, filled in only when the stored value is blank.

emailstring

The contact's email address. On upsert, overwrites the stored email.

customFieldsobject

JSON object of key/value pairs. Max 10,000 characters when stringified. Omit it entirely if you have none. On upsert, shallow-merged into the stored object.

The contact object

All three endpoints return the same object. Create and update return it as { contact }; list returns { contacts, pagination }. There is no status envelope.

idstringRequired

Opaque contact id. Pass it back as contactId when updating; do not parse it.

firstNamestring | nullRequired

The contact's first name, or null if never set.

lastNamestring | nullRequired

The contact's last name, or null if never set.

phoneNumberstringRequired

The contact's number in E.164. Note the asymmetry: requests take phone, responses return phoneNumber.

emailstring | nullRequired

The contact's email address, or null if never set.

customFieldsobject | nullRequired

Whatever JSON metadata you last stored. Replaced wholesale on update, never merged.

notestring | nullRequired

Free-form note stored on the contact.

createdAtstring (ISO-8601)Required

When the contact was first created.

updatedAtstring (ISO-8601)Required

When the contact was last modified.

Request

Example

Required: phone only. Optional: firstName, lastName, email, customFields.

{
  "phone": "+15551234567",          // required, E.164 like +12345678901
  "firstName": "Jane",              // optional
  "lastName": "Doe",                // optional
  "email": "jane@example.com",      // optional
  "customFields": {                 // optional object; omit if unused
    "shopifyCustomerId": "123",
    "shopifyOrderId": "456"
  }
}

Response

200

Wrapped as { contact }. List returns { contacts, pagination }.

{
  "contact": {
    "id": "string",
    "firstName": "string | null",
    "lastName": "string | null",
    "phoneNumber": "+15551234567",
    "email": "string | null",
    "customFields": { } | null,
    "note": "string | null",
    "createdAt": "ISO-8601",
    "updatedAt": "ISO-8601"
  }
}