Skip to content
Log in Start for free

AI Leads Engine

Leads

People in your lists. Suppressed addresses and addresses already in the workspace are refused.

GET/v1/leadsList leads POST/v1/leadsCreate a lead POST/v1/leads/bulkCreate leads in bulk GET/v1/leads/{id}Get a lead PATCH/v1/leads/{id}Update a lead DEL/v1/leads/{id}Delete a lead

List leads

GET/api/v1/leads

Newest first.

Any API key, read-only included.

Parameters

NameTypeDescription
list_id query uuid Only this list.
status query string Lead status, for example new.
per_page query integer Up to 100. Default 25.

Errors

  • 401Missing or invalid key
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl https://app.zicreach.com/api/v1/leads \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "data": [
        {
            "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22",
            "email": "jane@example.com",
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Example Ltd",
            "job_title": "Founder & CEO",
            "phone": null,
            "website": "example.com",
            "linkedin_url": "https://www.linkedin.com/in/janedoe",
            "location": "London, United Kingdom",
            "industry": "Software",
            "status": "new",
            "source": "api",
            "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
            "custom_fields": {
                "icebreaker": "Loved your talk at SaaStr"
            },
            "created_at": "2026-09-18T09:00:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "total": 1
    }
}

Create a lead

POST/api/v1/leads

Adds one lead to a list.

Needs a read and write API key.

Body

NameTypeDescription
emailrequired string Email address.
list_idrequired uuid The list to add to.
first_name string First name.
last_name string Last name.
company string Company name.
job_title string Job title.
phone string Phone number.
website string Company website.
linkedin_url string LinkedIn profile URL.
location string City or country.
industry string Industry.
custom_fields object Your own fields, usable as merge fields.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X POST https://app.zicreach.com/api/v1/leads \
  -H "Authorization: Bearer zk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","list_id":"9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10","first_name":"Jane","last_name":"Doe"}'
Response201
{
    "data": {
        "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22",
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "company": "Example Ltd",
        "job_title": "Founder & CEO",
        "phone": null,
        "website": "example.com",
        "linkedin_url": "https://www.linkedin.com/in/janedoe",
        "location": "London, United Kingdom",
        "industry": "Software",
        "status": "new",
        "source": "api",
        "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "custom_fields": {
            "icebreaker": "Loved your talk at SaaStr"
        },
        "created_at": "2026-09-18T09:00:00Z"
    }
}

Create leads in bulk

POST/api/v1/leads/bulk

Up to 500 leads in one call. Duplicates and suppressed addresses are counted and skipped.

Needs a read and write API key.

Body

NameTypeDescription
list_idrequired uuid The list to add to.
leadsrequired object[] Leads, each with email and any of the lead fields.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X POST https://app.zicreach.com/api/v1/leads/bulk \
  -H "Authorization: Bearer zk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"list_id":"9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10","leads":[{"email":"jane@example.com","first_name":"Jane"}]}'
Response201
{
    "data": {
        "created": 480,
        "duplicate": 15,
        "suppressed": 5
    }
}

Get a lead

GET/api/v1/leads/{id}

One lead.

Any API key, read-only included.

Parameters

NameTypeDescription
idrequired path uuid Lead id.

Errors

  • 401Missing or invalid key
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl https://app.zicreach.com/api/v1/leads/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10 \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "data": {
        "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22",
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "company": "Example Ltd",
        "job_title": "Founder & CEO",
        "phone": null,
        "website": "example.com",
        "linkedin_url": "https://www.linkedin.com/in/janedoe",
        "location": "London, United Kingdom",
        "industry": "Software",
        "status": "new",
        "source": "api",
        "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "custom_fields": {
            "icebreaker": "Loved your talk at SaaStr"
        },
        "created_at": "2026-09-18T09:00:00Z"
    }
}

Update a lead

PATCH/api/v1/leads/{id}

Send only the fields to change. custom_fields are merged, not replaced. The email cannot be changed.

Needs a read and write API key.

Parameters

NameTypeDescription
idrequired path uuid Lead id.

Body

NameTypeDescription
first_name string First name.
last_name string Last name.
company string Company name.
job_title string Job title.
phone string Phone number.
website string Company website.
linkedin_url string LinkedIn profile URL.
location string City or country.
industry string Industry.
custom_fields object Your own fields, usable as merge fields.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X PATCH https://app.zicreach.com/api/v1/leads/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10 \
  -H "Authorization: Bearer zk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe"}'
Response200
{
    "data": {
        "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22",
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "company": "Example Ltd",
        "job_title": "Founder & CEO",
        "phone": null,
        "website": "example.com",
        "linkedin_url": "https://www.linkedin.com/in/janedoe",
        "location": "London, United Kingdom",
        "industry": "Software",
        "status": "new",
        "source": "api",
        "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "custom_fields": {
            "icebreaker": "Loved your talk at SaaStr"
        },
        "created_at": "2026-09-18T09:00:00Z"
    }
}

Delete a lead

DELETE/api/v1/leads/{id}

Removes the lead.

Needs a read and write API key.

Parameters

NameTypeDescription
idrequired path uuid Lead id.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X DELETE https://app.zicreach.com/api/v1/leads/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10 \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "message": "Lead deleted."
}