Send a lead

Creates one lead for one Preferred Partner. 201 when this call inserts the row, whether the partner received it or it is queued for budget or payment.

Unknown fields are rejected. consentAt is required, must parse as a timestamp, and cannot be in the future. An invalid phone creates nothing.

Omit serviceId when serviceIdRequired is false. The API pins the single Default service, or the single non-Default service. Omit memberEmail when this account’s own system sent the lead. When memberEmail is set, it must be an active member of this account. An unrecognized email creates no lead and no idempotency row.

Send Idempotency-Key to make a retry safe for 24 hours. The key is scoped to this account and agreementId. The same key, phone, and email returns the original 201 and the original id. It does not create a second lead. A declined lead still replays that 201. The same key with a different phone or email is 409 and creates nothing. No Idempotency-Key header means every call creates a lead. A second call while the first is still running is 503 and creates nothing.

POST/api/leads

Authorization

X-CM-API-KEYAPI key · headerrequired

Account key from Integrations. Keys use the cm_ prefix.

Header parameters

Idempotency-Keystring

Makes a retry of this create safe for 24 hours. Scoped to this account and agreementId.

min length 1

Request body

requiredapplication/json

agreementIdstringrequired

min length 1

categoryIdstringrequired

min length 1

serviceIdstring | null

Required when the category's serviceIdRequired is true. Otherwise omit it or send null.

namestringrequired

min length 1

phonestringrequired

min length 1

emailstring<email>required

notesstring | null

consentAtstring<date-time>required

When the person consented. Required, must parse as a timestamp, and cannot be in the future.

memberEmailstring | null

Omit or send null when this account's own system sent the lead. When set, it must be an active member of this account.

Responses

201

The lead was created, or this idempotency key replayed the original create. Status starts at pending. delivered with pending is the accepted state.

One of:

DeliveredLead

idstringrequired

statusstringrequired

deliverystringrequired

QueuedLead

idstringrequired

statusstringrequired

deliverystringrequired

queuedReasonQueuedReasonrequired

Allowed:budget_exceededpayment_failed

401

The key is missing or unknown.

errorstringrequired

403

The key cannot send leads.

errorstringrequired

404

The agreement is outside this key.

errorstringrequired

409

The idempotency key was already used for a different phone or email. Nothing is created.

errorstringrequired

422

The body, phone, consent time, category, service, or member email is invalid. Nothing is created.

errorstringrequired

503

The lead was not saved, or the same idempotency key is still in flight. Retry a 503 that says the lead was not saved. A 503 creates nothing.

errorstringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Parameters

Idempotency-KeyheaderMakes a retry of this create safe for 24 hours. Scoped to this account and `agreementId`.

Bodyapplication/json

agreementIdstring*categoryIdstring*serviceIdstringRequired when the category's `serviceIdRequired` is true. Otherwise omit it or send null.namestring*phonestring*emailstring*notesstringconsentAtstring*When the person consented. Required, must parse as a timestamp, and cannot be in the future.memberEmailstringOmit or send null when this account's own system sent the lead. When set, it must be an active member of this account.

Request

curl -X POST 'https://www.comarketing.com/api/leads' \
  -H 'X-CM-API-KEY: YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "agreementId": "agr_id",
  "categoryId": "cat_id",
  "serviceId": null,
  "name": "Sam Rivera",
  "phone": "5551234567",
  "email": "sam@example.com",
  "notes": null,
  "consentAt": "2026-01-15T12:00:00.000Z",
  "memberEmail": null
}'

const response = await fetch("https://www.comarketing.com/api/leads", {
  method: "POST",
  headers: {
    "X-CM-API-KEY": "YOUR_API_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"agreementId\": \"agr_id\",\n  \"categoryId\": \"cat_id\",\n  \"serviceId\": null,\n  \"name\": \"Sam Rivera\",\n  \"phone\": \"5551234567\",\n  \"email\": \"sam@example.com\",\n  \"notes\": null,\n  \"consentAt\": \"2026-01-15T12:00:00.000Z\",\n  \"memberEmail\": null\n}"
});

import requests

response = requests.post(
    "https://www.comarketing.com/api/leads",
    headers={
        "X-CM-API-KEY": "YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"agreementId\": \"agr_id\",\n  \"categoryId\": \"cat_id\",\n  \"serviceId\": null,\n  \"name\": \"Sam Rivera\",\n  \"phone\": \"5551234567\",\n  \"email\": \"sam@example.com\",\n  \"notes\": null,\n  \"consentAt\": \"2026-01-15T12:00:00.000Z\",\n  \"memberEmail\": null\n}",
)

Response

{
  "id": "lead_id",
  "status": "pending",
  "delivery": "delivered"
}

{
  "id": "lead_id",
  "status": "pending",
  "delivery": "queued",
  "queuedReason": "budget_exceeded"
}

{
  "error": "Invalid API key."
}

{
  "error": "This key cannot send leads."
}

{
  "error": "Agreement is not an active Preferred Partner for this account."
}

{
  "error": "This idempotency key was already used for a different client."
}

{
  "error": "Request body is invalid."
}

{
  "error": "Phone number is invalid."
}

{
  "error": "The lead was not saved. Retry the request."
}

{
  "error": "A request with this idempotency key is still running."
}