Leads API

Manage lead lists and individual leads. Import leads, search, export, and organize them into lists.

List Lead Lists

GET/api/leads/lists

Retrieve all lead lists for the authenticated user.

Query Parameters

Parameter	Type	Description
`search`	string	Filter lists by name (case-insensitive)

Request — cURLcURL

curl --location --request GET 'http://outreach.weezly.com/api/leads/lists' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY'

Response — 200 OKJSON

{
  "lists": [
    {
      "id": "cm3list789abc",
      "name": "SaaS Founders — West Coast",
      "description": "Founders of B2B SaaS companies in CA, WA, OR",
      "userId": "user_123",
      "leadCount": 245,
      "createdAt": "2026-06-01T08:00:00.000Z",
      "updatedAt": "2026-06-05T14:30:00.000Z",
      "campaigns": [
        {
          "id": "cm3camp456",
          "name": "Q1 SaaS Outreach",
          "status": "ACTIVE"
        }
      ]
    }
  ]
}

Response Codes

200	Lists returned successfully
401	Unauthorized

Create Lead List

POST/api/leads/lists

Create a new lead list.

Request Body

Parameter	Type	Description
`name`required	string	Name of the lead list
`description`	string	Optional description

Request — cURLcURL

curl --location --request POST 'http://outreach.weezly.com/api/leads/lists' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Enterprise CTOs",
  "description": "CTOs at companies with 500+ employees"
}'

Response — 201 CreatedJSON

{
  "list": {
    "id": "cm3list_new123",
    "name": "Enterprise CTOs",
    "description": "CTOs at companies with 500+ employees",
    "userId": "user_123",
    "leadCount": 0,
    "createdAt": "2026-06-07T10:00:00.000Z",
    "updatedAt": "2026-06-07T10:00:00.000Z"
  }
}

Response Codes

201	List created successfully
400	Name is required
401	Unauthorized

Get Lead List

GET/api/leads/lists/:id

Get a lead list with paginated leads.

Query Parameters

Parameter	Type	Description
`search`	string	Search leads by name, company, or title
`page`	number	Page number (default: 1)
`limit`	number	Leads per page (default: 25)
`sortBy`	string	Sort field: addedAt, fullName, company (default: addedAt)
`sortOrder`	string	asc or desc (default: desc)

Request — cURLcURL

curl --location --request GET 'http://outreach.weezly.com/api/leads/lists/:id' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY'

Response — 200 OKJSON

{
  "list": {
    "id": "cm3list789abc",
    "name": "SaaS Founders — West Coast",
    "description": "Founders of B2B SaaS companies",
    "leadCount": 245
  },
  "leads": [
    {
      "id": "cm3lead_001",
      "firstName": "Sarah",
      "lastName": "Chen",
      "fullName": "Sarah Chen",
      "headline": "CEO at TechStartup Inc.",
      "jobTitle": "CEO",
      "company": "TechStartup Inc.",
      "email": "sarah@techstartup.com",
      "phone": null,
      "location": "San Francisco, CA",
      "linkedinUrl": "https://linkedin.com/in/sarahchen",
      "photoUrl": "https://media.licdn.com/...",
      "connectionStatus": "UNKNOWN",
      "source": "SEARCH",
      "createdAt": "2026-06-01T08:00:00.000Z"
    }
  ],
  "total": 245,
  "page": 1,
  "totalPages": 10
}

Response Codes

200	List and leads returned
404	List not found
401	Unauthorized

Update Lead List

PATCH/api/leads/lists/:id

Update a lead list's name or description.

Request Body

Parameter	Type	Description
`name`	string	New name for the list
`description`	string	New description

Request — cURLcURL

curl --location --request PATCH 'http://outreach.weezly.com/api/leads/lists/:id' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "SaaS Founders — Updated",
  "description": "Updated description for the list"
}'

Response Codes

200	List updated
400	Name cannot be empty
404	List not found
401	Unauthorized

Delete Lead List

DELETE/api/leads/lists/:id

Delete a lead list and all its entries. Leads themselves are not deleted.

Request — cURLcURL

curl --location --request DELETE 'http://outreach.weezly.com/api/leads/lists/:id' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY'

Response — 200 OKJSON

{
  "ok": true
}

Response Codes

200	List deleted
404	List not found
401	Unauthorized

Add Lead to List

POST/api/leads/lists/:id/leads

Add a lead to the list. If a lead with the same LinkedIn URL already exists for this user, it will be linked to the list instead of duplicated.

Request Body

Parameter	Type	Description
`firstName`	string	First name
`lastName`	string	Last name
`fullName`	string	Full name
`headline`	string	LinkedIn headline
`jobTitle`	string	Job title
`company`	string	Company name
`email`	string	Email address
`phone`	string	Phone number
`location`	string	Location
`linkedinUrl`	string	LinkedIn profile URL

Request — cURLcURL

curl --location --request POST 'http://outreach.weezly.com/api/leads/lists/:id/leads' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "firstName": "Marcus",
  "lastName": "Johnson",
  "fullName": "Marcus Johnson",
  "headline": "VP Engineering at ScaleUp",
  "company": "ScaleUp Solutions",
  "email": "marcus@scaleup.io",
  "linkedinUrl": "https://linkedin.com/in/marcusjohnson"
}'

Response — 201 CreatedJSON

{
  "lead": {
    "id": "cm3lead_new456",
    "firstName": "Marcus",
    "lastName": "Johnson",
    "fullName": "Marcus Johnson",
    "headline": "VP Engineering at ScaleUp",
    "company": "ScaleUp Solutions",
    "email": "marcus@scaleup.io",
    "linkedinUrl": "https://linkedin.com/in/marcusjohnson",
    "source": "MANUAL",
    "createdAt": "2026-06-07T10:00:00.000Z"
  },
  "alreadyInList": false
}

Response Codes

201	Lead added to list
404	List not found
401	Unauthorized

Remove Lead from List

DELETE/api/leads/lists/:id/leads/:leadId

Remove a lead from the list. The lead record itself is not deleted.

Request — cURLcURL

curl --location --request DELETE 'http://outreach.weezly.com/api/leads/lists/:id/leads/:leadId' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY'

Response — 200 OKJSON

{ "ok": true }

Response Codes

200	Lead removed from list
404	Lead or list not found
401	Unauthorized

Bulk Delete Leads

POST/api/leads/lists/:id/leads/bulk-delete

Remove multiple leads from the list at once.

Request Body

Parameter	Type	Description
`leadIds`required	string[]	Array of lead IDs to remove

Request — cURLcURL

curl --location --request POST 'http://outreach.weezly.com/api/leads/lists/:id/leads/bulk-delete' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "leadIds": [
    "cm3lead_001",
    "cm3lead_002",
    "cm3lead_003"
  ]
}'

Response — 200 OKJSON

{ "deleted": 3 }

Export Leads

GET/api/leads/lists/:id/export

Export all leads from a list as JSON. Returns the full lead data with enrichment information.

Request — cURLcURL

curl --location --request GET 'http://outreach.weezly.com/api/leads/lists/:id/export' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY'

Response — 200 OKJSON

{
  "list": { "id": "cm3list789abc", "name": "SaaS Founders" },
  "leads": [
    {
      "firstName": "Sarah",
      "lastName": "Chen",
      "fullName": "Sarah Chen",
      "headline": "CEO at TechStartup Inc.",
      "company": "TechStartup Inc.",
      "email": "sarah@techstartup.com",
      "linkedinUrl": "https://linkedin.com/in/sarahchen",
      "location": "San Francisco, CA"
    }
  ],
  "total": 245
}

Update Lead

PATCH/api/leads/:leadId

Update a lead's fields.

Request Body

Parameter	Type	Description
`firstName`	string	First name
`lastName`	string	Last name
`email`	string	Email address
`phone`	string	Phone number
`company`	string	Company name
`jobTitle`	string	Job title
`location`	string	Location

Request — cURLcURL

curl --location --request PATCH 'http://outreach.weezly.com/api/leads/:leadId' \
  --header 'X-API-KEY: sk_live_YOUR_API_KEY'

Response — 200 OKJSON

{
  "lead": {
    "id": "cm3lead_001",
    "firstName": "Sarah",
    "lastName": "Chen-Williams",
    "email": "sarah@newemail.com",
    "updatedAt": "2026-06-07T10:05:00.000Z"
  }
}