Kashew
Get StartedAPI ReferenceGuide

Leads

Create, read, update, and manage leads in your CRM.

GET/leads

List leads with pagination, search, and filters.

Query Parameters

page(integer)

Page number (default: 1)

pageSize(integer)

Items per page (default: 20, max: 500)

search(string)

Search by name, company, or email

status(string)

Filter: Accepted, Rejected

sort(string)

score_desc, score_asc, name_asc, name_desc, recent

isArchived(boolean)

Show archived leads (default: false)

Request
curl -X GET "https://kashew.ai/api/v1/leads?page=1&pageSize=20&search=acme" \
  -H "Authorization: Bearer kshw_xxxxxxxx_xxxxx..."
POST/leads

Create a new lead.

Request Body
{
  "personName": "Jane Smith",
  "companyName": "Acme Corp",
  "email": "jane@acme.com",
  "phone": "+1 555-0123",
  "jobTitle": "VP of Sales",
  "industry": "SaaS / Software",
  "website": "https://acme.com",
  "country": "United States",
  "linkedinProfileUrl": "https://linkedin.com/in/janesmith"
}
201Response
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created"
}
GET/leads/:id

Get a single lead by ID.

Request
curl -X GET "https://kashew.ai/api/v1/leads/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer kshw_xxxxxxxx_xxxxx..."
PUT/leads/:id

Update a lead's fields.

Request
curl -X PUT "https://kashew.ai/api/v1/leads/a1b2c3d4..." \
  -H "Authorization: Bearer kshw_xxxxxxxx_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"status": "Qualified", "jobTitle": "CTO"}'
DELETE/leads/:id

Permanently delete a lead.

Requires scope: crm:write. JWT only — not available via API key.

POST/leads/bulk

Create multiple leads in a single request (max 500).

Request Body
{
  "leads": [
    {
      "companyName": "Alpha Inc",
      "personName": "Alice Green",
      "email": "alice@alpha.com",
      "jobTitle": "CEO",
      "industry": "Finance"
    },
    {
      "companyName": "Beta Corp",
      "personName": "Bob Brown",
      "email": "bob@beta.com",
      "jobTitle": "CTO",
      "industry": "Technology"
    }
  ],
  "options": {
    "onDuplicate": "skip",
    "defaultStatus": "New",
    "stopOnError": false
  }
}

Options

onDuplicate(string)

"skip" (default) or "overwrite"

defaultStatus(string)

New (default), Contacted, Qualified

assignToOwnerId(string)

UUID — assign all leads to a specific user (admin/manager only)

stopOnError(boolean)

false (default) — best-effort; true — abort on first error

200Response
{
  "batchId": "bulk_uuid",
  "summary": { "total": 2, "created": 2, "updated": 0, "skipped": 0, "failed": 0 },
  "results": [
    { "index": 0, "status": "created", "id": "lead-uuid-1" },
    { "index": 1, "status": "created", "id": "lead-uuid-2" }
  ]
}
POST/leads/:id/convert

Convert a lead into an account (and optionally a contact).

Request Body
{
  "createContact": true,
  "accountData": {
    "name": "Acme Corp",
    "industry": "Technology",
    "type": "Enterprise",
    "status": "Active"
  },
  "contactData": {
    "first_name": "Jane",
    "last_name": "Doe",
    "role_type": "decision_maker",
    "email": "jane@acme.com",
    "job_title": "CTO"
  }
}
200Response
{
  "success": true,
  "accountId": "new-account-uuid",
  "contactId": "new-contact-uuid"
}

Returns 409 if the lead has already been converted. The response includes a pointer to the current account.

POST/lead-enrichment

Trigger AI enrichment for a lead (generates insights, scoring, recommendations).

Request
curl -X POST "https://kashew.ai/api/v1/lead-enrichment" \
  -H "Authorization: Bearer kshw_xxxxxxxx_xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'