Matchai Docs

Add a contactComing soon

Adds a lead, a client or a professional to your contacts.

Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.
POST
/contacts

Coming soon. Adds a lead, a client or a professional to your contacts. When the email or phone matches an existing contact, nothing is added and the call returns 409 contact_exists. For an enquiry from a website form, POST /enquiries does the matching for you.

Scopes: contacts:write

Pricing: Included with the connection.

Authorization

headerAuthorizationBearer <matchai_<base62>>

A personal API key, sent as Authorization: Bearer matchai_…. Create keys in Matchai under Settings → Connectors → Advanced (for developers). A key starts with matchai_ followed by letters and digits, carries the scopes chosen when it was created, and can be revoked at any time. Keys reach only the account that created them: to serve other professionals, use Connect with Matchai.

Scope: contacts:write

Header Parameters

Idempotency-Key?string

A unique string (a UUID works). Retrying with the same key within 24 hours returns the first response instead of acting twice. Reusing a key with a different body returns 409 idempotency_key_reused.

Length1 <= length <= 255

Request Body

application/json
  1. body

Needs a phone number or an email. If a contact with the same email or phone already exists, returns 409 contact_exists with its id in error.param.

type?ContactType

lead: a potential customer. client: a customer you have worked with. professional: a peer, such as another broker, a notary or a lender.

Value in"lead""client""professional"
first_name?string

First name, as given.

Length1 <= length <= 100
last_name?string

Last name, if given. Never guess a split.

Lengthlength <= 100
email*unknown
phone?string

Phone, preferably E.164.

Lengthlength <= 40
company?string

Company.

Lengthlength <= 200
notes?string

Notes.

Lengthlength <= 2000
source_listing_id?string

The listing they came through.

Length1 <= length <= 64

Response Body

The new contact.

application/json
  1. response

A person in your contacts. Only you (and your team, for team contacts) can see this record; the person cannot.

id*string

Contact id.

Length1 <= length <= 64
type*ContactType

lead: a potential customer. client: a customer you have worked with. professional: a peer, such as another broker, a notary or a lender.

Value in"lead""client""professional"
first_name?|

First name, as you entered it.

last_name?|

Last name.

display_name*string

Name as Matchai shows it.

email?|

Email.

Formatemail
phone?|

Phone, E.164.

company?|

Company.

profession?|

Profession, in words.

notes?|

Your notes.

source*ContactSource

How the contact reached you: from a listing, your Matchai Site, your Matchai Page, added by hand (direct), a referral, an import, an invitation, a scanned business card, or your own website through the API (website). New values may be added.

Value in"listing""site""page""direct""referral""import""invitation""business_card""website"
source_listing_id?|

The listing they came through.

Length1 <= length <= 64
matchai_user?|

Their Matchai account, when they have one.

conversation_id?|

Your direct conversation with them, when there is one.

Length1 <= length <= 64
erased*boolean

True when the person deleted their Matchai account: their identity is gone, your history with them is kept.

lead?|null
client?|null
professional?|null
created_at*string

Added.

Formatdate-time
updated_at*string

Last changed.

Formatdate-time
Example Request
curl -X POST 'https://api.matchai.co/v1/contacts' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d' \  -H 'Content-Type: application/json' \  -d '{  "type": "lead",  "first_name": "string",  "email": null}'
Example Response
{  "id": "string",  "type": "lead",  "first_name": "string",  "last_name": "string",  "display_name": "string",  "email": "user@example.com",  "phone": "string",  "company": "string",  "profession": "string",  "notes": "string",  "source": "listing",  "source_listing_id": "string",  "matchai_user": {    "user_id": "string",    "username": "string",    "avatar_url": "http://example.com"  },  "conversation_id": "string",  "erased": true,  "lead": {    "stage": "welcome",    "temperature": "cold",    "readiness": "exploring",    "lifecycle_stage": "new",    "score": 0,    "budget": {      "min": 0,      "max": 0,      "currency": "string"    },    "timeline": "string",    "preferences": {      "bedrooms": 0,      "bathrooms": 0,      "min_sqft": 0,      "max_sqft": 0,      "property_types": [        "string"      ],      "areas": [        "string"      ],      "features": [        "string"      ]    },    "updated_at": "2019-08-24T14:15:22Z"  },  "client": {    "converted_from_lead_at": "2019-08-24T14:15:22Z",    "property_interests": [      "string"    ],    "transactions": [      {        "type": "purchase",        "date": "2019-08-24",        "value": 0,        "listing_id": "string",        "notes": "string"      }    ],    "preferred_channel": "email"  },  "professional": {    "relationship": "peer",    "specializations": [      "string"    ],    "referral_count": 0,    "notes": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}