Prospect contacts

Create, match, read, update and delete prospect contacts through the /prospects endpoints.

A prospect contact is a person you're prospecting who isn't yet a Contact at one of your Accounts. In the API they live at /prospects: every /prospects endpoint reads or writes prospect contacts. A prospect contact can be linked to a Prospect Company.

POST /prospects is built for capturing prospect contacts from forms and other tools: it matches on email, so sending the same person twice updates them instead of creating a duplicate.

The prospect contact object#

source_id (where the prospect contact came from) can be set on create and update but isn't returned in responses.

{
  "id": "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63",
  "first_name": "Sam",
  "last_name": "Lee",
  "email": "sam.lee@fabrikam.example",
  "phone": "+1 646 555 0123",
  "job_title": "Operations Director",
  "linkedin_url": null,
  "stage_id": "rps_new",
  "owner_id": "5b8d1f3a-7e2c-4a9b-b6d4-1c3e5f7a9b20",
  "lead_company_id": "cm3k9x2p10004qz8f7h2d1a6b",
  "converted_at": null,
  "archived_at": null,
  "created_at": "2026-11-12T09:30:00.000Z",
  "updated_at": "2026-11-12T09:30:00.000Z",
  "custom_fields": {
    "budget_band": "50k-100k",
    "wants_demo": true
  }
}

Stage IDs#

List prospect contacts#

GET /prospects · Scope: prospects:read

Returns prospect contacts newest first, with their custom fields. Archived prospect contacts aren't listed.

Query parameters#

Example#

curl "https://crm.empiraa.app/api/v1/prospects?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://crm.empiraa.app/api/v1/prospects?limit=100", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const { data, meta } = await res.json();

Response 200#

An array of prospect contact objects in data. meta has cursor, hasMore and total (the number of prospect contacts in the workspace).

{
  "data": [ { "id": "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63", "first_name": "Sam", "last_name": "Lee", "email": "sam.lee@fabrikam.example", "stage_id": "rps_new", "custom_fields": {} } ],
  "meta": { "cursor": null, "total": 1, "hasMore": false },
  "error": null
}

(Shortened: each item is a full prospect contact object.)

Create or update a prospect contact#

POST /prospects · Scope: prospects:write · Supports Idempotency-Key

If a prospect contact with the same email already exists in the workspace, it's updated with the fields you send and the response is 200 with "_action": "updated". Otherwise a new one is created and the response is 201 with "_action": "created".

Request body#

All fields are optional, but send at least an email or a name.

Email from other fields. If email is missing or empty, the first other field whose name contains "email" and whose value contains "@" is used as the email. This lets form tools that name the field differently (such as work_email) still match.

When a prospect contact is matched, only the fields you send are changed. An empty first_name or last_name doesn't overwrite an existing name.

Example#

curl -X POST https://crm.empiraa.app/api/v1/prospects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2c7e4a90-6b1d-4f3e-8a5c-0d9b7e3f1a26" \
  -d '{
    "email": "sam.lee@fabrikam.example",
    "first_name": "Sam",
    "last_name": "Lee",
    "job_title": "Operations Director",
    "source_id": "rls_website",
    "notes": "Requested a demo from the pricing page.",
    "custom_fields": { "budget_band": "50k-100k" }
  }'

const res = await fetch("https://crm.empiraa.app/api/v1/prospects", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    email: "sam.lee@fabrikam.example",
    first_name: "Sam",
    last_name: "Lee",
    job_title: "Operations Director",
    source_id: "rls_website",
    notes: "Requested a demo from the pricing page.",
    custom_fields: { budget_band: "50k-100k" },
  }),
});
const { data } = await res.json();
console.log(data._action); // "created" or "updated"

Response 201 or 200#

{
  "data": {
    "id": "e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63",
    "first_name": "Sam",
    "last_name": "Lee",
    "email": "sam.lee@fabrikam.example",
    "phone": null,
    "job_title": "Operations Director",
    "linkedin_url": null,
    "stage_id": "rps_new",
    "owner_id": null,
    "lead_company_id": null,
    "converted_at": null,
    "archived_at": null,
    "created_at": "2026-11-12T09:30:00.000Z",
    "updated_at": "2026-11-12T09:30:00.000Z",
    "custom_fields": { "budget_band": "50k-100k", "wants_demo": null },
    "_action": "created"
  },
  "meta": { "cursor": null },
  "error": null
}

Errors#

Webhook events: prospect.created for a new prospect contact, prospect.updated for a matched one. Also starts any Autopilot workflows that run when a prospect contact is created, updated or changes stage.

Get a prospect contact#

GET /prospects/{id} · Scope: prospects:read

Path parameters#

Example#

curl https://crm.empiraa.app/api/v1/prospects/e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63 \
  -H "Authorization: Bearer YOUR_API_KEY"

await fetch("https://crm.empiraa.app/api/v1/prospects/e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

Response 200#

The prospect contact object in data.

Errors#

Update a prospect contact#

PATCH /prospects/{id} · Scope: prospects:write

Send only the fields you want to change.

Request body#

Example#

curl -X PATCH https://crm.empiraa.app/api/v1/prospects/e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage_id": "rps_qualified", "owner_id": "5b8d1f3a-7e2c-4a9b-b6d4-1c3e5f7a9b20"}'

await fetch("https://crm.empiraa.app/api/v1/prospects/e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "rps_qualified", owner_id: "5b8d1f3a-7e2c-4a9b-b6d4-1c3e5f7a9b20" }),
});

Response 200#

The updated prospect contact object in data.

Errors#

Webhook events: prospect.updated.

Delete a prospect contact#

DELETE /prospects/{id} · Scope: prospects:write

Moves the prospect contact to Recently deleted in Signal. It stays there for 30 days, during which it can be restored from Settings → Recently deleted. After 30 days it's removed for good.

Example#

curl -X DELETE https://crm.empiraa.app/api/v1/prospects/e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63 \
  -H "Authorization: Bearer YOUR_API_KEY"

await fetch("https://crm.empiraa.app/api/v1/prospects/e4b7c1d9-2f6a-4b3e-9c8d-5a1f7e2b4c63", {
  method: "DELETE",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

Response 204#

No body.

Errors#

Webhook events: prospect.deleted.