Skip to main content
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 '
{
  "First Name": "Jane",
  "Last Name": "Smith",
  "Contact Type": "Tenant",
  "Email": "jane@example.com",
  "Mobile Phone": "+14155551234",
  "customFields": {
    "DbJT6rMdnuds7vSbP": true,
    "5D8LYiyMt54aKD7x9": "Primary Tenant"
  }
}
'
{
  "_id": "abc123",
  "First Name": "Jane",
  "Last Name": "Smith",
  "Full Name": "Jane Smith",
  "Contact Type": "Tenant",
  "Title": "Property Manager",
  "Company": "",
  "Email": [
    "jane@example.com"
  ],
  "Phone": [
    {
      "number": "+14155551234",
      "type": "mobile"
    }
  ],
  "companyId": "comp456",
  "imageUrl": "https://cdn.getaptly.com/photos/abc123.jpg",
  "customFields": {
    "DbJT6rMdnuds7vSbP": {
      "name": "Named On Lease",
      "dataType": "boolean-checkbox",
      "optional": true,
      "value": true
    },
    "5D8LYiyMt54aKD7x9": {
      "name": "Occupant Role",
      "dataType": "text",
      "optional": true,
      "value": "Primary Tenant"
    }
  }
}

Authorizations

​
x-token
string
header
required

Body

application/json
​
_id
string

Provide to update an existing contact by ID.

​
First Name
string
​
Last Name
string
​
Contact Type
string

Contact type name (e.g. Tenant). Must match an existing type in the company.

​
Title
string

Job title.

​
Company
string
​
Email
string<email>
​
Home Phone
string
​
Mobile Phone
string
​
Work Phone
string
​
imageUrl
string

URL of the contact's photo. Must end in .jpg, .jpeg, or .png. Stored and returned in subsequent reads.

​
customFields
object

Custom fields for the contact, keyed by field ID. The valid field IDs depend on the contact's type. Pass { "<fieldId>": value } — the field definition is looked up automatically. On read, each entry is enriched to { name, dataType, optional, value }.

Response

Contact created or updated.

​
_id
string
​
First Name
string
​
Last Name
string
​
Full Name
string
​
Contact Type
string
​
Title
string

Job title.

​
Company
string
​
Email
string[]
​
Phone
object[]
​
companyId
string

ID of the company this contact belongs to.

​
imageUrl
string | null

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

​
customFields
object

Custom fields enriched with their definitions. Each key is a field ID; each value is { name, dataType, optional, value }.