Matchai Docs

List contactsComing soon

Returns your contacts, newest first. query searches every contact by name and company; all its words must match.

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

Coming soon. Returns your contacts, newest first. query searches every contact by name and company; all its words must match.

Scopes: contacts:read

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:read

Query Parameters

limit?integer

How many results per page.

Range1 <= value <= 100
Default25
cursor?string

The next_cursor of the previous page. Cursors expire after 24 hours.

Lengthlength <= 512
type?string

Only this kind of contact.

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

Words from the name or the company.

Lengthlength <= 200
source?string

Only contacts that came this way.

Value in"listing""site""page""direct""referral""import""invitation""business_card""website"
email?string

Find the contact with this email.

Formatemail
phone?string

Find the contact with this phone number.

Lengthlength <= 40
updated_since?string

Only contacts changed after this time.

Formatdate-time

Response Body

One page of contacts.

application/json
  1. response

One page of results. Pass next_cursor as cursor to get the next page; it is null on the last page.

data*array<>
next_cursor*|

Cursor for the next page, or null when there are no more results.

Example Request
curl -X GET 'https://api.matchai.co/v1/contacts'
Example Response
{  "data": [    {      "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"    }  ],  "next_cursor": "string"}