Leads

Create a lead

Adds a lead to the workspace, optionally straight into a campaign.

Leads are deduplicated across the whole workspace by the person they resolve to, so posting the same email twice returns the same lead with created: false and a 200 rather than creating a second row. That is what makes a retry safe — there is no idempotency key to manage, and it also catches the same person arriving from two different integrations.

name is required, plus at least one of email, phone or linkedinUrl: without one of those there is no way to recognise this person again. When campaignId is given, any workflow with a Lead enters campaign trigger fires, exactly as it would for a lead added in the Cockpit.

Custom fields sent on create are applied to the lead that is returned — including when that is an existing lead. Re-running an import therefore updates the values in place rather than dropping them with the duplicate, so the same migration can be run twice and converge.

POST

leads

Create a lead

curl --request POST \
  --url https://backend.leadey.ai/v1/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Priya Raman",
  "email": "priya.raman@northwind.co.uk",
  "phone": "+442071838750",
  "company": "Northwind Logistics",
  "title": "Head of Revenue Operations",
  "campaignId": "fnl_Q3OutboundUK",
  "source": "website-form",
  "customFields": {
    "legacy_record_id": "REC-90412",
    "legacy_created_at": "2023-04-11"
  }
}
'

import requests

url = "https://backend.leadey.ai/v1/leads"

payload = {
    "name": "Priya Raman",
    "email": "priya.raman@northwind.co.uk",
    "phone": "+442071838750",
    "company": "Northwind Logistics",
    "title": "Head of Revenue Operations",
    "campaignId": "fnl_Q3OutboundUK",
    "source": "website-form",
    "customFields": {
        "legacy_record_id": "REC-90412",
        "legacy_created_at": "2023-04-11"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Priya Raman',
    email: 'priya.raman@northwind.co.uk',
    phone: '+442071838750',
    company: 'Northwind Logistics',
    title: 'Head of Revenue Operations',
    campaignId: 'fnl_Q3OutboundUK',
    source: 'website-form',
    customFields: {legacy_record_id: 'REC-90412', legacy_created_at: '2023-04-11'}
  })
};

fetch('https://backend.leadey.ai/v1/leads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "id": "lead_8Kq2mXvR",
    "name": "Priya Raman",
    "firstName": "Priya",
    "lastName": "Raman",
    "title": "Head of Revenue Operations",
    "company": "Northwind Logistics",
    "email": "priya.raman@northwind.co.uk",
    "phone": "+442071838750",
    "linkedinUrl": "https://www.linkedin.com/in/priyaraman",
    "status": "pending",
    "source": "linkedin-search",
    "score": 78,
    "campaignId": "fnl_Q3OutboundUK",
    "campaignName": "Q3 outbound, UK logistics",
    "createdAt": "2026-07-14T09:12:44.000Z",
    "created": false
  }
}

{
  "data": {
    "id": "lead_8Kq2mXvR",
    "name": "Priya Raman",
    "firstName": "Priya",
    "lastName": "Raman",
    "title": "Head of Revenue Operations",
    "company": "Northwind Logistics",
    "email": "priya.raman@northwind.co.uk",
    "phone": "+442071838750",
    "linkedinUrl": "https://www.linkedin.com/in/priyaraman",
    "status": "pending",
    "source": "linkedin-search",
    "score": 78,
    "campaignId": "fnl_Q3OutboundUK",
    "campaignName": "Q3 outbound, UK logistics",
    "createdAt": "2026-07-14T09:12:44.000Z",
    "created": true
  }
}

{
  "error": {
    "message": "One of email, phone or linkedinUrl is required",
    "details": null
  }
}

{
  "error": {
    "message": "Invalid or revoked API key.",
    "details": null
  }
}

{
  "error": {
    "message": "This API key is read-only. Create a key with write access in Settings → API Keys.",
    "details": null
  }
}

{
  "error": {
    "message": "Lead not found",
    "details": null
  }
}

{
  "error": {
    "message": "Rate limit exceeded. Retry in 42s.",
    "details": null
  }
}

Authorizations

Authorization

string

header

required

Your API key, created in the Leadey dashboard under Settings → API Keys. Send it as Authorization: Bearer leadey_sk_live_….

Body

application/json

name

string

required

The person's full name.

string<email>

Work email address.

phone

string

Phone number in E.164 format.

linkedinUrl

string

Their LinkedIn profile URL.

company

string

Company name.

title

string

Job title.

campaignId

string

Add the lead straight into this campaign.

source

string

Where the lead came from. Shows in the Cockpit and can be filtered on with GET /leads?source=. Defaults to api.

customFields

object

Custom field values, keyed by field key. A field that doesn't exist yet is created automatically, so a migration doesn't have to pre-declare its columns — which makes this the place to park foreign identifiers such as a record id from your previous CRM.

Keys are slugified (Legacy Record ID is stored as legacy_record_id), and the response echoes the canonical keys so you can see exactly what landed. Values are stored as text; numbers, dates and booleans are coerced.

Show child attributes

Example:

{
  "legacy_record_id": "REC-90412",
  "legacy_created_at": "2023-04-11"
}

Response

This person was already in the workspace. The existing lead is returned unchanged.

data

object

required

Show child attributes

Create a lead

curl --request POST \
  --url https://backend.leadey.ai/v1/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Priya Raman",
  "email": "priya.raman@northwind.co.uk",
  "phone": "+442071838750",
  "company": "Northwind Logistics",
  "title": "Head of Revenue Operations",
  "campaignId": "fnl_Q3OutboundUK",
  "source": "website-form",
  "customFields": {
    "legacy_record_id": "REC-90412",
    "legacy_created_at": "2023-04-11"
  }
}
'

import requests

url = "https://backend.leadey.ai/v1/leads"

payload = {
    "name": "Priya Raman",
    "email": "priya.raman@northwind.co.uk",
    "phone": "+442071838750",
    "company": "Northwind Logistics",
    "title": "Head of Revenue Operations",
    "campaignId": "fnl_Q3OutboundUK",
    "source": "website-form",
    "customFields": {
        "legacy_record_id": "REC-90412",
        "legacy_created_at": "2023-04-11"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Priya Raman',
    email: 'priya.raman@northwind.co.uk',
    phone: '+442071838750',
    company: 'Northwind Logistics',
    title: 'Head of Revenue Operations',
    campaignId: 'fnl_Q3OutboundUK',
    source: 'website-form',
    customFields: {legacy_record_id: 'REC-90412', legacy_created_at: '2023-04-11'}
  })
};

fetch('https://backend.leadey.ai/v1/leads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "id": "lead_8Kq2mXvR",
    "name": "Priya Raman",
    "firstName": "Priya",
    "lastName": "Raman",
    "title": "Head of Revenue Operations",
    "company": "Northwind Logistics",
    "email": "priya.raman@northwind.co.uk",
    "phone": "+442071838750",
    "linkedinUrl": "https://www.linkedin.com/in/priyaraman",
    "status": "pending",
    "source": "linkedin-search",
    "score": 78,
    "campaignId": "fnl_Q3OutboundUK",
    "campaignName": "Q3 outbound, UK logistics",
    "createdAt": "2026-07-14T09:12:44.000Z",
    "created": false
  }
}

{
  "data": {
    "id": "lead_8Kq2mXvR",
    "name": "Priya Raman",
    "firstName": "Priya",
    "lastName": "Raman",
    "title": "Head of Revenue Operations",
    "company": "Northwind Logistics",
    "email": "priya.raman@northwind.co.uk",
    "phone": "+442071838750",
    "linkedinUrl": "https://www.linkedin.com/in/priyaraman",
    "status": "pending",
    "source": "linkedin-search",
    "score": 78,
    "campaignId": "fnl_Q3OutboundUK",
    "campaignName": "Q3 outbound, UK logistics",
    "createdAt": "2026-07-14T09:12:44.000Z",
    "created": true
  }
}

{
  "error": {
    "message": "One of email, phone or linkedinUrl is required",
    "details": null
  }
}

{
  "error": {
    "message": "Invalid or revoked API key.",
    "details": null
  }
}

{
  "error": {
    "message": "This API key is read-only. Create a key with write access in Settings → API Keys.",
    "details": null
  }
}

{
  "error": {
    "message": "Lead not found",
    "details": null
  }
}

{
  "error": {
    "message": "Rate limit exceeded. Retry in 42s.",
    "details": null
  }
}

Account

Leads

Notes

Campaigns

Metrics

Companies

Contacts

Meetings

Opportunities

Pipelines

Calls

Tasks

Reference

Create a lead

Authorizations

Body

Response