Leads API

All lead endpoints are prefixed with /api/leads and require authentication.

Write operations (create, update, delete) require an API key with full scope.

List leads

GET /api/leads

Returns a paginated list of leads in your workspace.

Query parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Results per page (max 100)
`status`	string		Filter by status: `new`, `contacted`, `qualified`, `converted`, `closed`
`sourceId`	string		Filter by source UUID
`search`	string		Search by name, email, phone, or company
`startDate`	string		Filter leads created after this ISO date
`endDate`	string		Filter leads created before this ISO date
`assignedTo`	string		Filter by assigned user ID, or `unassigned`
`duplicates`	string		`only` to show only duplicates, `exclude` to hide them

Example:

curl "https://leads.500rockets.io/api/leads?status=new&limit=10" \
  -H "X-API-Key: 5l_live_..."

Response:

{
  "data": [
    {
      "id": "lead_abc123",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+1234567890",
      "company": "Acme Corp",
      "status": "new",
      "score": 78,
      "source": { "id": "src_xyz", "name": "Website Form" },
      "assignedTo": null,
      "createdAt": "2026-03-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "pages": 5
  }
}

Get a lead

GET /api/leads/:id

Returns a single lead with full details.

curl "https://leads.500rockets.io/api/leads/lead_abc123" \
  -H "X-API-Key: 5l_live_..."

Get lead events

GET /api/leads/:id/events

Returns the activity timeline for a lead (scoring events, status changes, etc.).

curl "https://leads.500rockets.io/api/leads/lead_abc123/events" \
  -H "X-API-Key: 5l_live_..."

Update lead status

PUT /api/leads/:id/status

Moves a lead to a new status. Requires full scope.

curl -X PUT "https://leads.500rockets.io/api/leads/lead_abc123/status" \
  -H "X-API-Key: 5l_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "contacted" }'

Body:

Field	Type	Required	Description
`status`	string	Yes	One of: `new`, `contacted`, `qualified`, `converted`, `closed`

Update lead notes

PUT /api/leads/:id/notes

Sets or updates the notes on a lead. Requires full scope.

curl -X PUT "https://leads.500rockets.io/api/leads/lead_abc123/notes" \
  -H "X-API-Key: 5l_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Spoke with Jane, interested in Pro plan." }'

Manage lead tags

Add a tag

POST /api/leads/:id/tags

curl -X POST "https://leads.500rockets.io/api/leads/lead_abc123/tags" \
  -H "X-API-Key: 5l_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "hot-lead" }'

Remove a tag

DELETE /api/leads/:id/tags/:tagId

curl -X DELETE "https://leads.500rockets.io/api/leads/lead_abc123/tags/tag_xyz" \
  -H "X-API-Key: 5l_live_..."

Assign a lead

PUT /api/leads/:id/assign

Assigns a lead to a team member. Requires full scope.

curl -X PUT "https://leads.500rockets.io/api/leads/lead_abc123/assign" \
  -H "X-API-Key: 5l_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "userId": "usr_member123" }'

Set userId to null to unassign.

Get lead duplicates

GET /api/leads/:id/duplicates

Returns leads that have been flagged as duplicates of this lead.

Merge leads

POST /api/leads/:id/merge

Merges a duplicate lead into the primary lead. Requires full scope.

curl -X POST "https://leads.500rockets.io/api/leads/lead_abc123/merge" \
  -H "X-API-Key: 5l_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "duplicateId": "lead_dup456" }'

Delete a lead

DELETE /api/leads/:id

Permanently deletes a lead and its associated data. Requires full scope.

curl -X DELETE "https://leads.500rockets.io/api/leads/lead_abc123" \
  -H "X-API-Key: 5l_live_..."

Lead stats

GET /api/leads/stats

Returns aggregated lead counts by status.

{
  "total": 142,
  "byStatus": {
    "new": 45,
    "contacted": 30,
    "qualified": 38,
    "converted": 20,
    "closed": 9
  }
}

Export leads (CSV)

GET /api/leads/export

Downloads all leads as a CSV file. Supports the same filters as the list endpoint.

curl "https://leads.500rockets.io/api/leads/export?status=qualified" \
  -H "X-API-Key: 5l_live_..." \
  -o leads.csv

Import leads (CSV)

POST /api/leads/import

Uploads a CSV file to create leads in bulk. Requires full scope.

curl -X POST "https://leads.500rockets.io/api/leads/import" \
  -H "X-API-Key: 5l_live_..." \
  -F "[email protected]"

The CSV must include a header row. Recognized columns: email, firstName, lastName, phone, company.