What the Wiza API Does
The Wiza API is designed for developers who need accurate, real-time contact enrichment. It is widely used to:
Build custom enrichment workflows
Power data enrichment products and applications
Use your own Wiza API key within supported integration partners (Clay, n8n, Apollo.io)
The API can find and verify:
Work and personal email addresses
Mobile phone numbers (up to 3 per profile)
LinkedIn profile details (name, title, company, location, bio, work history, skills, education, and more)
Company-level details (domain, industry, headcount, funding, revenue, HQ location, and more)
The full list of returnable fields is available in the Data Dictionary at docs.wiza.co.
Account Setup
Create a free admin account at wiza.co/signup
Activate your account using the link sent to your email
Once logged in, go to Settings → API (under the profile icon in the top-right corner) to manage keys and credits
API Credits
API credits are purchased in advance and deducted only when data is successfully returned. Credits are valid for 12 months from purchase.
How credits are deducted:
Phone numbers — 5 credits if at least one phone number is returned (
enrichment_level: "phone"or"full")Emails — 2 credits if at least one "valid" email is returned (
enrichment_level: "partial"or"full")LinkedIn profile — 1 credit if a LinkedIn URL is found and matched (
enrichment_level: "none")
No data returned = no credits charged.
Purchasing credits:
Enterprise API plans — Click Contact Sales in Settings → API for volume discounts, or book a call directly
Direct purchase via UI — Use the slider in Settings → API to buy smaller amounts; a valid credit card must be on file in Billing
After a request completes, you can confirm credits deducted in the response under the credits object: api_credits.total, api_credits.email_credits, api_credits.phone_credits, api_credits.scrape_credits.
API Key Management
Go to Settings → API and click New API Key
Enter a name, assign the API User (match to the account admin), and click Create New Key
Each account can generate up to 3 API keys total — this includes previously disabled keys
Keys can be disabled at any time but once 3 have been created, no additional keys can be generated
Authorization
Every API request requires a Bearer token in the Authorization header:
Authorization: Bearer YOUR_API_KEY
401 Unauthorized is returned when the API key is missing, invalid, disabled, or does not exist. The request format must be Bearer YOUR_API_KEY — not just the key alone.
Recommended Inputs
For the /api/individual_reveals endpoint, provide one of the following per request, listed from highest to lowest performing:
LinkedIn URL (strongly recommended) — highest accuracy
Full name + company domain — domains are unique; better than company name alone
Full name + company name — acceptable, but company names may have duplicates
Email address — use only when other options are unavailable
Input fields: profile_url, full_name, domain, company, email
Enrichment Levels
Set enrichment_level in the request body to control what data is retrieved:
"none"— LinkedIn profile info and company details only (no contact data)"partial"— Email addresses (work and/or personal viaemail_options)"phone"— Mobile phone numbers only"full"— Emails + phones
How Individual Reveals Work (Two-Step Flow)
All enrichment follows the same two-step pattern:
Step 1 — Start a reveal:
POST https://wiza.co/api/individual_reveals
Send your input data and enrichment level. The response includes an id.
Step 2 — Retrieve results:
GET https://wiza.co/api/individual_reveals/{id}
Use the id from Step 1 to fetch enriched data. Alternatively, configure a webhook to receive results automatically when processing completes.
Average processing times:
Phone numbers — 0–15 seconds (~4 seconds average)
Personal emails — 0–15 seconds (~4 seconds average)
Work emails — 0–380 seconds (~25 seconds average)
LinkedIn profile — 0–15 seconds (~5 seconds average)
For phone numbers — parse phone_number (E.164, highest quality), number_pretty (human-readable), or number from the phones array. Wiza may return up to 3 numbers. Both "type": "mobile" and "type": "other" are mobile numbers. Do not rely solely on the mobile_phone field.
For email addresses — use email_options to specify "accept_work": true and/or "accept_personal": true. Parse email, email_type, and email_status from the emails array.
For LinkedIn profile info — additional fields (beyond defaults) can be enabled in Settings → Data & Export → Advanced Columns.
Bulk Enrichment
Submit multiple requests to /api/individual_reveals in parallel. Requests process concurrently up to your concurrency limit; additional requests queue automatically and begin processing as slots free up.
Starter API — 5 concurrent requests
Enterprise API — 15+ concurrent requests (scales higher)
The queue limit is 200× your concurrency limit. If the queue fills, additional requests return errors until capacity is available. Example: concurrency of 15 = queue limit of 3,000.
Webhooks
Configure a default webhook URL in Settings → API to receive results automatically without polling. Wiza sends a POST request to your endpoint when a reveal completes or fails.
Your endpoint must be publicly accessible and return a
200status to acknowledge receiptRespond immediately with
200, then process asynchronously to avoid timeoutsCheck
status.codein the payload:200= success,400= failed revealEnable Send All Callbacks to receive webhooks for all enrichment activity on your account, not just API-initiated requests
Override the default URL per-request by including
"callback_url"in the request body
Webhook signature verification: Each webhook includes an x-auth-key header containing a SHA256 hash of your API key. Verify this to confirm the request came from Wiza.
Retry behavior: If your endpoint returns a non-2xx response, Wiza retries up to 3 times. If your endpoint consistently returns 404 or 403, Wiza will stop retrying for that request.
Status Codes & Errors
400 — Invalid request format or parameters
401 — Authentication failed or missing credentials
403 — Forbidden
404 — Assigned user not granted access, or record not found
429 — Usage limits exceeded
Billing issue special case: A billing issue returns a 200 HTTP response, but the reveal does not actually run. The record will show status: "failed" with fail_error: "billing_issue". This means processing was blocked due to missing credits or an unresolved payment issue.
If you encounter a status code not listed above, contact Wiza support for assistance.
Integrations
Wiza's API key can be used directly within the following partner platforms:
Clay — Use Wiza within Clay for enrichment workflows
n8n — Use Wiza within n8n for automated contact enrichment pipelines
Apollo.io — Use Wiza with Apollo.io waterfall enrichment
Setup guides for each are available at docs.wiza.co.
FAQ
Q: Where do I find my API key?
A: Settings → API (under the profile icon in the top right). Click New API Key to create one.
Q: How many API keys can I have?
A: Up to 3 total per account — including any previously disabled keys. Once 3 have been created, no more can be generated.
Q: Am I charged if no data is returned?
A: No — credits are only deducted when data is successfully found and returned.
Q: How long do API credits last?
A: 12 months from the date of purchase.
Q: What's the best input for the highest match rate?
A: LinkedIn URL is the strongest input. Full name + company domain is the next best. Email address should only be used when other options aren't available.
Q: What's the difference between enrichment levels?
A: "none" = LinkedIn/company profile data only; "partial" = emails; "phone" = phone numbers; "full" = emails + phones.
Q: How do I do bulk enrichment?
A: Submit multiple requests to the individual_reveals endpoint in parallel. Requests process concurrently up to your plan's concurrency limit, with overflow queued automatically.
Q: Do I have to poll for results?
A: No — configure a webhook URL in Settings → API and results will be delivered to your endpoint automatically when each reveal completes.
Q: My request returned a 200 but the reveal failed — why?
A: Check for fail_error: "billing_issue" in the response. This means the reveal was blocked due to missing credits or an unresolved payment.
Q: What's the concurrency limit?
A: Starter API = 5 concurrent requests; Enterprise API = 15+ (scales higher). Queue limit = 200× your concurrency limit.
Q: Where can I find the full API reference?
A: The full documentation — including endpoint schemas, code examples in curl, JavaScript, Python, and Ruby — is at docs.wiza.co.
💡 Quick-start checklist: ✅ Create account → ✅ Purchase API credits (Settings → API) → ✅ Generate API key → ✅ Add Authorization: Bearer YOUR_API_KEY to every request → ✅ POST to /api/individual_reveals with your input + enrichment level → ✅ GET results using the returned id (or configure a webhook)