Inicio rápidoPróximamente

Crea una clave de API.

Abre Configuración → Conectores, despliega Avanzado (para desarrolladores) y ve a Claves de API. Crea una clave, ponle un nombre (por ejemplo, "Inicio rápido") y dale tres alcances: profile:read, listings:read y contacts:write.

Copia la clave de inmediato. Matchai la muestra una sola vez. Empieza con matchai_. Guárdala en una variable de entorno, nunca en tu código:

export MATCHAI_API_KEY="matchai_…"

Cada clave pertenece a la conexión Acceso a la API de tu cuenta, que aparece en la página Conectores como cualquier otra conexión. Consulta Claves de API para conocer los alcances, la rotación y la revocación.

Comprueba a qué cuenta llega la clave. GET /v1/me devuelve la cuenta en cuyo nombre actúa tu clave.

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

Una respuesta abreviada:

{
  "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 es full, comfortable, low o empty. La Energía Matchai nunca se muestra como un número. Los nombres y los ids de estos ejemplos son ficticios.

Lista tus anuncios. GET /v1/listings devuelve los anuncios que puedes administrar, primero los que cambiaron más recientemente. Las listas vienen en páginas: pasa limit para definir el tamaño de una página, y el next_cursor de una página como el cursor de la siguiente.

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

Una respuesta abreviada, con un anuncio:

{
  "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
}

Para mantener sincronizada una copia de tus anuncios, pasa updated_since con la hora de tu última sincronización. Consulta paginación para ver el ciclo completo.

Agrega un contacto. POST /v1/contacts agrega un prospecto, un cliente o un profesional. Envía un Idempotency-Key con cada POST: si tu solicitud excede el tiempo de espera, puedes repetirla con la misma clave y Matchai no agregará el contacto dos veces.

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"
  }'

Una respuesta 201 devuelve el contacto nuevo, abreviado aquí:

{
  "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"
}

Cuando el correo electrónico o el número de teléfono ya pertenece a uno de tus contactos, Matchai no agrega nada y responde 409 con el código contact_exists. Por eso el código de arriba lo comprueba.