API Reference

Import a contact

http

POST /contacts

Creates a new contact in DashCRM, or updates an existing one if the email already exists. Requires a read & write API key.

Required fields

email - The contact's email address

Optional fields

firstName, lastName, name, phone, mobilePhone, tag, tags, companyName, notes, source, sourceExternalOriginalName, buyerType, budget, referredBy, addressLine1, addressLine2, cityName, regionName, suburbName, postalCode, country, stateOrProvince, projectId, unitId, assignedAccountUserId

All optional fields can be omitted or sent as null.

Source values

Website, Referral, Social Media, Open Home, Agent, Other

If you send a source that isn't in this list, DashCRM will store it as Other and save your original value in sourceExternalOriginalName. If you omit source entirely, DashCRM stores Other and sets sourceExternalOriginalName to "API Import".

Buyer type values

First Home Buyer, Investor, Downsizer, Upgrader, Other

Tags and assignment

Use tag for a single tag, or tags for multiple tags. tags can be either an array or a comma-separated string:

json

{
  "email": "lead@example.com",
  "tag": "Website Lead",
  "tags": ["VIP Buyer", "Auckland"]
}

DashCRM normalizes duplicate tag labels, creates missing tags on your account, and links the tags to the imported contact.

Use assignedAccountUserId to assign the contact to an active user on your account.

How matching works

When you import a contact, DashCRM checks if a contact with that email already exists:

No match found - a new contact is created.

One match found - only empty fields on the existing contact are filled in. Existing values stay unchanged, and archived matches are made active again.

If notes is included - DashCRM records it as a dated activity entry instead of merging into the contact's freeform notes field. If the latest activity already has the same note body, the duplicate entry is skipped.

Multiple matches found - the request is rejected with a 409 error to avoid ambiguity.

Linking to a project or unit

You can link an imported contact to a project (and optionally a specific unit). The project must be live and belong to your account. If you include a unitId, you must also include the projectId it belongs to.

Example request

bash

curl "https://app.dashcrm.co/api/v1/contacts" \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "lead@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "phone": "+64211234567",
    "tag": "Website Lead",
    "tags": ["VIP Buyer", "Auckland"],
    "source": "Other",
    "sourceExternalOriginalName": "Ad Campaign",
    "notes": "Downloaded the brochure",
    "projectId": "project_123",
    "assignedAccountUserId": "account_user_123"
  }'

Example response

json

{
  "action": "created",
  "contactId": "contact_123",
  "email": "lead@example.com",
  "matchedBy": null,
  "filledFields": [
    "name",
    "phone_primary",
    "notes",
    "stage",
    "source",
    "imported_at",
    "assigned_account_user",
    "contact_tags"
  ],
  "linkedProjectId": "project_123",
  "linkedUnitId": null
}

If an existing contact was updated, action will be "merged" and matchedBy will be "email".

← Previous

Stocklist & project endpoints

Integrations