Create or update a contact

curl --request POST \
  --url https://core-api.getaptly.com/api/contacts \
  --header 'Content-Type: application/json' \
  --header 'x-token: <api-key>' \
  --data '
{
  "firstname": "Jane",
  "lastname": "Smith",
  "email": "[email protected]",
  "phone": [
    {
      "number": "+15555550100",
      "type": "mobile"
    }
  ],
  "contactType": "Tenant"
}
'

{
  "_id": "<string>",
  "uuid": "<string>",
  "firstname": "<string>",
  "lastname": "<string>",
  "fullName": "<string>",
  "duogram": "<string>",
  "photoId": "<string>",
  "imageUrl": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "typeId": "<string>",
  "companyId": "<string>",
  "address": {},
  "title": "<string>",
  "alerts": [
    {}
  ],
  "company": "<string>",
  "isCompany": true
}

Contacts

Create or update a contact

Creates a new contact or updates an existing one (upsert).

Lookup order:

If _id is provided, finds by ID.
Otherwise finds by first email address.
If no match is found, creates a new contact.

Body formats — either native or legacy (capitalized keys) are accepted:

Native: firstname, lastname, email (string or array), phone (array of {number, type}), typeId, contactType, isCompany, title, company, imageUrl, customFields

Legacy: "First Name", "Last Name", Email, "Mobile Phone", "Work Phone", "Home Phone", "Contact Type", Title, Company

Returns the enriched contact with custom fields populated by their type definitions.

POST

api

contacts

Create or update a contact

curl --request POST \
  --url https://core-api.getaptly.com/api/contacts \
  --header 'Content-Type: application/json' \
  --header 'x-token: <api-key>' \
  --data '
{
  "firstname": "Jane",
  "lastname": "Smith",
  "email": "[email protected]",
  "phone": [
    {
      "number": "+15555550100",
      "type": "mobile"
    }
  ],
  "contactType": "Tenant"
}
'

{
  "_id": "<string>",
  "uuid": "<string>",
  "firstname": "<string>",
  "lastname": "<string>",
  "fullName": "<string>",
  "duogram": "<string>",
  "photoId": "<string>",
  "imageUrl": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "typeId": "<string>",
  "companyId": "<string>",
  "address": {},
  "title": "<string>",
  "alerts": [
    {}
  ],
  "company": "<string>",
  "isCompany": true
}

Authorizations

x-token

string

header

required

Body

application/json

_id

string

Existing contact ID — when provided, updates that contact.

firstname

string

lastname

string

One or more email addresses.

phone

object[]

Show child attributes

typeId

string

Contact type ID.

contactType

string

Contact type name (alternative to typeId — resolved to an ID automatically).

isCompany

boolean

title

string

company

string

imageUrl

string

Absolute URL to a JPG or PNG photo.

customFields

object

Map of custom field ID to value. Unknown field IDs are rejected.

Response

Contact created or updated.

_id

string

MongoDB ObjectId of the contact.

uuid

string

firstname

string

lastname

string

fullName

string

Computed display name (first + last, or company name for org records).

duogram

string

Two-letter initials derived from first and last name.

photoId

string | null

imageUrl

string | null

CDN thumbnail URL for the contact's photo, or null if none.

string

phone

string

typeId

string

companyId

string

address

object

title

string

alerts

object[]

company

string

Company name — populated when isCompany is true.

isCompany

boolean

List contacts Look up contacts by email