Skip to main content

Zeliq Enrichment API

Updated this week

What is the Zeliq Enrichment API?

The Zeliq Enrichment API lets you find verified emails and phone numbers programmatically — without using the Zeliq dashboard. It's designed for teams that want to integrate Zeliq's enrichment engine into their own tools, workflows, or applications (n8n, Make, Clay, custom CRMs, etc.).

The API is asynchronous: you send a request with a callback URL, and Zeliq posts the results back to that URL when the enrichment is complete.

Getting started

Where do I find my API key?

Go to Settings > API in your Zeliq workspace. You need admin access to view the key. Your API key starts with sk- and is unique to your organization.

How do I authenticate?

Add your API key in the x-api-key header of every request:

x-api-key: sk-your-api-key-here

⚠️ Do not use Bearer token authentication. The only supported method is the x-api-key header.

Available endpoints

1. Check your credit balance

GET <https://app.zeliq.com/api/credits/balance>

Response:

{   "credit_balance": 4500 }

This endpoint is not subject to rate limits.

2. Enrich an email address

POST <https://app.zeliq.com/api/contact/enrich/email>

Request body — Option A (with LinkedIn URL):

{   "linkedin_url": "<https://linkedin.com/in/johndoe>",   "callbackUrl": "<https://your-server.com/webhook>" }

Request body — Option B (without LinkedIn URL):

{   "first_name": "John",   "last_name": "Doe",   "company": "Acme Inc",   "callbackUrl": "<https://your-server.com/webhook>" }

Required fields

  • callbackUrl — always required, must be a valid HTTP or HTTPS URL

  • Either linkedin_url OR the combination of first_name + last_name + (company or domain)

Optional fields

  • domain — the company's website domain (alternative to company)

Cost

  • 1 credit per enrichment (0 credits on Advanced and Enterprise plans)

  • Credits are refunded if no email is found

3. Enrich a phone number

POST <https://app.zeliq.com/api/contact/enrich/phone>

Request body:

{   "linkedin_url": "<https://linkedin.com/in/johndoe>",   "callbackUrl": "<https://your-server.com/webhook>" }

OR:

{   "email": "[email protected]",   "callbackUrl": "<https://your-server.com/webhook>" }

Required fields

  • callbackUrl — always required

  • Either linkedin_url OR email

Cost

  • 10 credits per enrichment

  • Credits are refunded if no phone number is found

How does the async flow work?

  1. You send your enrichment request with a callbackUrl

  2. You receive an immediate response (HTTP 202) with a jobId

  3. Zeliq processes the enrichment using 10+ data providers (waterfall)

  4. Zeliq posts the result to your callbackUrl when ready

Immediate response you receive (HTTP 202):

{   "status": 202,   "message": "Request accepted, results will be sent to the callback URL",   "jobId": "a1b2c3d4-e5f6-..." }

💡 Pro tip: Include your own identifier in the callback URL (e.g. ?contactId=123) to match results with your records.

Callback payloads

Email enrichment callback

Posted to your callbackUrl when the enrichment is complete:

{   "credit_used": 1,   "contact": {     "first_name": "John",     "last_name": "Doe",     "domain": "acme.com",     "linkedin_url": "<https://linkedin.com/in/johndoe>",     "most_probable_email": "[email protected]",     "most_probable_email_status": "valid",     "emails": [       { "email": "[email protected]", "status": "valid" },       { "email": "[email protected]", "status": "catch-all" }     ]   } }

  • most_probable_email — the best email found

  • most_probable_email_status — verification result (valid, catch-all, invalid, etc.)

  • emails — all emails found with their verification status

  • credit_used — actual credits charged (0 if nothing found)

Phone enrichment callback

{   "credit_used": 10,   "contact": {     "linkedin_url": "<https://linkedin.com/in/johndoe>",     "email": "[email protected]",     "most_probable_phone": "+33612345678",     "phones": [       { "phone": "+33612345678" },       { "phone": "+33698765432" }     ]   } }

  • most_probable_phone — the best phone number found

  • phones — all phone numbers found

  • credit_used — actual credits charged (0 if nothing found)

Rate limits

Rate limits depend on your Zeliq plan:

Plan

Per minute

Per hour

Per day

Free

50

200

600

Starter

200

400

2,000

Essential / Advanced / Enterprise

600

2,000

6,000

The credit balance endpoint (GET /api/credits/balance) is exempt from rate limits.

Error codes & troubleshooting

400 — Bad Request

What it means: Your request is missing required fields or has invalid data.

Common messages:

  • "linkedin_url or email is required" — for phone enrichment, you must provide at least one of these

  • "Either linkedin_url OR (first_name, last_name, and company or domain) are required" — for email enrichment

  • Validation error on callbackUrl — make sure it's a valid URL starting with http:// or https://

What to do: Check the required fields for the endpoint you're calling. Make sure callbackUrl is present and valid.

401 — Unauthorized

What it means: Authentication failed.

Common messages:

  • "API key is required" — you forgot the x-api-key header

  • "Invalid API key" — the key doesn't exist or was regenerated

What to do:

  • Make sure you're sending the key in the x-api-key header (not as Bearer token, not as a query parameter)

  • Go to Settings > API to verify your key

  • If you recently regenerated your key, update it in your integration

402 — Payment Required

What it means: Your organization has no credits left.

Message: "No Credit Remaining"

What to do: Purchase more credits or upgrade your plan in Settings > Billing.

423 — Locked

What it means: Your user account has been blocked.

Message: "User is blocked"

What to do: Contact support at [email protected].

429 — Too Many Requests

What it means: You've exceeded the rate limit for your plan.

Response format:

{   "statusCode": 429,   "error": "Too Many Requests",   "message": "Rate limit exceeded. Please try again later.",   "limits": {     "perMinute": 200,     "perHour": 400,     "perDay": 2000   } }

What to do:

  • The limits object tells you your current plan limits

  • Wait a moment before retrying

  • If you consistently hit limits, consider upgrading your plan

  • Implement exponential backoff in your integration

FAQ

Can I use the API without a callback URL?

No. The callbackUrl is required for all enrichment requests. The API is fully asynchronous — you send a request, and the results are delivered to your callback URL.

How long does an enrichment take?

Most enrichments complete within a few seconds to a few minutes. In rare cases, it can take longer depending on provider availability.

Am I charged if no data is found?

No. Credits are only charged for successful enrichments. If no email or phone number is found, credit_used will be 0 in the callback.

Can I enrich both email and phone in one call?

No. Email and phone enrichments are separate endpoints. You need to make two API calls.

Does the callback_url field name work too?

Yes. Both callbackUrl and callback_url are accepted in the request body.

What email statuses can I receive?

The most_probable_email_status field can return: valid, catch-all, invalid, unknown. Only verified emails are returned by default.

Is there a synchronous mode?

No. The API only works in asynchronous mode with a callback URL.

Can I track where my API calls come from?

Yes. Add an x-request-origin header (max 50 characters) to tag your requests for tracking purposes.

What plans have access to the API?

All plans (Free, Starter, Essential, Advanced, Enterprise) have API access. The difference is in rate limits and credit costs.

Can multiple users share the same API key?

The API key is tied to the organization, not individual users. All members share the same key and rate limits.

Quick reference card

Email enrichment

Phone enrichment

Endpoint

POST /api/contact/enrich/email

POST /api/contact/enrich/phone

Required input

linkedin_url OR (first_name • last_name • company/domain)

linkedin_url OR email

Callback URL

Required

Required

Credit cost

1 credit (0 on Advanced/Enterprise)

10 credits

Refund if not found

Yes

Yes

Auth

x-api-key header

x-api-key header

Related Articles
Welcome to ZELIQ!
Enrich your lead's data
🔌 How to use ZELIQ with Clay
Enrich contacts in n8n: The right way
Did this answer your question?