QuickstartComing soon

Create an API key.

Open Settings → Connectors, expand Advanced (for developers) and go to API keys. Create a key, name it (for example "Quickstart") and give it three scopes: profile:read, listings:read and contacts:write.

Copy the key straight away. Matchai shows it once. It starts with matchai_. Keep it in an environment variable, never in your code:

export MATCHAI_API_KEY="matchai_…"

Every key belongs to your account's API access connection, which appears on the Connectors page like any other connection. See API keys for scopes, rotation and revocation.

Check which account the key reaches. GET /v1/me returns the account your key acts for.

curl https://api.matchai.co/v1/me \
  -H "Authorization: Bearer $MATCHAI_API_KEY"

An abridged answer:

{
  "user_id": "3f1c9a2e-7b44-4d0e-9c1a-5e8f2b6d4a10",
  "professional_id": "8a2d4f6b-1c3e-4a5b-9d7f-0e2c4b6a8d1f",
  "username": "camilletremblay",
  "display_name": "Camille Tremblay",
  "job_title": "Residential real estate broker",
  "language": "fr-CA",
  "timezone": "America/Toronto",
  "site_id": "0f1a2b3c-4d5e-4f6a-9b7c-8d9e0f1a2b3c",
  "page_url": "https://camilletremblay.matchai.pro",
  "energy": { "balance_state": "comfortable" }
}

energy.balance_state is full, comfortable, low or empty. Matchai Energy is never shown as a number. The names and ids in these examples are made up.

List your listings. GET /v1/listings returns the listings you can manage, most recently changed first. Lists come in pages: pass limit to size a page, and the next_cursor of one page as the cursor of the next.

curl -G https://api.matchai.co/v1/listings \
  -H "Authorization: Bearer $MATCHAI_API_KEY" \
  -d status=published \
  -d limit=5

An abridged answer, with one listing:

{
  "data": [
    {
      "id": "b7e4c2a1-9f3d-4e6b-8a5c-1d2f3e4a5b6c",
      "slug": "condo-rue-fabre-plateau-mont-royal",
      "url": "https://camilletremblay.matchai.co/listings/condo-rue-fabre-plateau-mont-royal",
      "status": "published",
      "availability": "available",
      "title": "Bright corner condo steps from Parc La Fontaine",
      "price": { "amount": 649000, "currency": "CAD" },
      "updated_at": "2026-10-18T09:41:52Z"
    }
  ],
  "next_cursor": null
}

To keep a copy of your listings in sync, pass updated_since with the time of your last sync. See pagination for the full loop.

Add a contact. POST /v1/contacts adds a lead, a client or a professional. Send an Idempotency-Key with every POST: if your request times out, you can repeat it with the same key and Matchai will not add the contact twice.

curl https://api.matchai.co/v1/contacts \
  -H "Authorization: Bearer $MATCHAI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "lead",
    "first_name": "Julien",
    "last_name": "Bouchard",
    "email": "julien.bouchard@example.com"
  }'

A 201 answer returns the new contact, abridged here:

{
  "id": "c5d8e1f2-3a4b-4c6d-9e8f-7a6b5c4d3e2f",
  "type": "lead",
  "first_name": "Julien",
  "last_name": "Bouchard",
  "display_name": "Julien Bouchard",
  "email": "julien.bouchard@example.com",
  "created_at": "2026-10-16T19:12:44Z"
}

When the email or phone number already belongs to one of your contacts, Matchai adds nothing and answers 409 with the code contact_exists. That is why the code above checks for it.