POST /api/v1/contacts

Create or update up to 1,000 contacts in a single request. Each row is matched and upserted by externalId; rows with no match are created.

Recommended push order: companies → contacts → deals. Push companies first so companyExternalId links resolve on your first contacts push, then push deals so their contactExternalId/companyExternalId links resolve too.

Request

POST /api/v1/contacts HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "contacts": [
    {
      "name": "Jane Buyer",
      "email": "jane@acme.com",
      "companyExternalId": "SHOP-CO-1",
      "externalId": "SHOP-C-1"
    },
    {
      "name": "John Prospect",
      "company": "Globex",
      "lifecycleStage": "LEAD"
    }
  ]
}

The contacts array must contain at least 1 item and at most 1,000.

Response — 200 (all rows succeeded)

When every row in the batch succeeds, the response status is 200:

{
  "created": 1,
  "updated": 1,
  "errors": 0,
  "results": [
    { "index": 0, "status": "created", "id": "cmq2abc2def3ghi4jkl5" },
    { "index": 1, "status": "updated", "id": "cmq7mno7pqr8stu9vwx0" }
  ]
}

Each entry in results corresponds to the contact at that position in your request array (zero-indexed).

Response — 207 Multi-Status (partial success)

When at least one row fails validation, the response status is 207. Failed rows appear in results with "status": "error":

{
  "created": 1,
  "updated": 0,
  "errors": 1,
  "results": [
    { "index": 0, "status": "created", "id": "cmq2abc2def3ghi4jkl5" },
    {
      "index": 1,
      "status": "error",
      "error": "companyExternalId: no company found for \"NOPE\"."
    }
  ]
}

A row that fails validation does not abort the batch. Valid rows are written; failed rows are skipped and reported per-index in results. This includes an unresolved companyExternalId — no contact is created for that row.

Merge on update

When a row matches an existing contact (by externalId), only the fields present in your request body are updated. Fields you omit retain their current values — this is a merge update, not a full replace.

For example, sending only { "externalId": "SHOP-C-1", "status": "CUSTOMER" } updates the status without touching name, email, company, or any other field.

Company linking

Link a contact to a company by companyId, companyExternalId, or a free-text company name (see The Contact object for priority order). Push companies first if you plan to use companyExternalId.

Quickstart

export AL_KEY="alk_live_xxx"

# Push your contacts — run this on a schedule to keep them in sync
curl -s -X POST https://agentlyleads.com/api/v1/contacts \
  -H "Authorization: Bearer $AL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "name": "Jane Buyer",
        "email": "jane@acme.com",
        "companyExternalId": "SHOP-CO-1",
        "externalId": "SHOP-C-1"
      }
    ]
  }'

A typical integration is a nightly job in your CRM or e-commerce backend that reads its customer/contact list and POSTs it here. The first run creates everything; every later run updates by externalId.