# Account Setup
Source: https://docs.wiza.co/account-access/account-setup
Create and configure your Wiza account
1. If you don't already have an account, create a free admin account using [this sign-up link](https://wiza.co/signup)
2. Activate your account using the activation link sent to your email
3. Once logged in, go to [**Settings → API**](https://wiza.co/app/settings/api) (under the profile icon in the top-right corner)
# API Key Management
Source: https://docs.wiza.co/account-access/api-key-management
Manage and rotate your API keys
Manage your API keys from [**Settings → API**](https://wiza.co/app/settings/api).
* Each account can generate up to **three (3) API keys** in total.
* Keys can be disabled as needed, but once three keys are created, no additional keys can be generated. This includes keys that were previously disabled.
# Generate an API Key
Source: https://docs.wiza.co/account-access/generate-api-key
Create your API key for authentication
1. In [**Settings → API**](https://wiza.co/app/settings/api), click **New API Key**
2. Enter a name for the key
3. Assign the API User to match the account Admin
4. Click **Create New Key**
# Purchasing API Credits
Source: https://docs.wiza.co/account-access/purchasing-api-credits
How to purchase and manage API credits
API credits can be purchased in one of two ways:
* **Enterprise API plans** – In [**Settings → API**](https://wiza.co/app/settings/api), click **Contact Sales** to inquire about larger credit plans that include volume discounts. Alternatively, you can book directly using [this link](https://schedule.wiza.co/meet/kj-chow/call).
* **Direct purchase via UI** – Use the [slider in the User Interface](https://wiza.co/app/settings/api) to buy smaller amounts of credits. Ensure a valid credit card is on file in the [**Billing**](https://wiza.co/app/settings/billing) tab to process the payment and apply the credits.
API credits have a validity of **12 months**.
# Company Enrichment
Source: https://docs.wiza.co/api-reference/company-enrichment/company-enrichment
/swagger/v1/openapi.yaml post /api/company_enrichments
>
Enrich company data instantly. You can provide a company name, company domain, LinkedIn ID, or LinkedIn slug to get comprehensive company information.
This endpoint returns company data immediately, including industry, size, revenue, funding information, location, and more.
The enrichment costs 2 API credits per successful request. Credits are only charged when company data is successfully found and returned.
Rate limits apply: 30 requests per minute, 43,200 requests per day.
# Get Credits
Source: https://docs.wiza.co/api-reference/credits/get-credits
/swagger/v1/openapi.yaml get /api/meta/credits
Get the number of credits remaining in your account.
# Get Individual Reveal
Source: https://docs.wiza.co/api-reference/individual-reveals/get-individual-reveal
/swagger/v1/openapi.yaml get /api/individual_reveals/{id}
Get the individual reveal by id.
# Start Individual Reveal
Source: https://docs.wiza.co/api-reference/individual-reveals/start-individual-reveal
/swagger/v1/openapi.yaml post /api/individual_reveals
>
Start an individual reveal. An individual reveal is a single contact enrichment. You can provide a name, company, and domain, or an email, or a LinkedIn profile URL.
> Either `company` (company name) or `domain` is required when using contact details.
Once the reveal is completed, an update will be posted to the webhook URL as configured in your [ account settings ]( http://wiza.co/app/settings/api ). The payload will be the same as the response of the Get Individual Reveal endpoint. If you wish to do added authentication, the headers in the webhook request will include `x-auth-key` which will be a SHA256 hash of your api key.
You can get the status of the individual reveal by calling the `GET /api/individual_reveals/:id` endpoint.
# Create List
Source: https://docs.wiza.co/api-reference/lists/create-list
/swagger/v1/openapi.yaml post /api/lists
>
Create a list of people to enrich.
Once the list is completed, an update will be posted to the webhook URL as configured in your [ account settings ]( http://wiza.co/app/settings/api ). The payload will be the same as the response of this endpoint. If you wish to do added authentication, the headers in the webhook request will include `x-auth-key` which will be a SHA256 hash of your api key.
You can get the status of the list by calling the `GET /api/lists/:id` endpoint.
And you can get the contacts by calling the `GET /api/lists/:id/contacts` endpoint.
**Note:** Please check the status of the list as it may fail sometimes due to LinkedIn rate limiting.
# Get List
Source: https://docs.wiza.co/api-reference/lists/get-list
/swagger/v1/openapi.yaml get /api/lists/{id}
Get the list with the given id
# Get List Contacts
Source: https://docs.wiza.co/api-reference/lists/get-list-contacts
/swagger/v1/openapi.yaml get /api/lists/{id}/contacts
>
Get contacts for a list.
By default a json response is returned. To get a csv response, append `.csv` to the url path.
# Continue prospect search
Source: https://docs.wiza.co/api-reference/prospect-lists/continue-prospect-search
/swagger/v1/openapi.yaml post /api/prospects/continue_search
Continue with your previous search
# Create prospect list
Source: https://docs.wiza.co/api-reference/prospect-lists/create-prospect-list
/swagger/v1/openapi.yaml post /api/prospects/create_prospect_list
Create a list of prospects that match your filters
# Company search
Source: https://docs.wiza.co/api-reference/prospect/company-search
/swagger/v1/openapi.yaml post /api/accounts/search
Search for companies using firmographic, location, growth, and funding filters. Returned companies cost 0.5 API credits each.
# Prospect search
Source: https://docs.wiza.co/api-reference/prospect/prospect-search
/swagger/v1/openapi.yaml post /api/prospects/search
Find the number of prospects that match your search filters
# Search Locations
Source: https://docs.wiza.co/api-reference/prospects/search-locations
/swagger/v1/openapi.yaml get /api/meta/location_autocomplete
Search locations and regional groups accepted by the Prospect API location and company_location filters.
# Search Technologies
Source: https://docs.wiza.co/api-reference/prospects/search-technologies
/swagger/v1/openapi.yaml get /api/meta/technology_autocomplete
Search the technology catalog for names and slugs accepted by the Prospect API technologies filter.
# Wiza API Documentation
Source: https://docs.wiza.co/index
Find and verify contact information for sales and recruiting prospects
Welcome to Wiza's API documentation. Find emails, phone numbers, and contact details with industry-leading accuracy.
***
## Overview
Learn about the Wiza API and what data is available.
* [Introduction](/overview/introduction) - Get started with Wiza's API
* [Key Functionality](/overview/key-functionality) - Find emails, phone numbers, Profile Details, and company details
* [Data Dictionary](/overview/data-dictionary) - Explore all available data fields
* [Usage Limits](/overview/usage-limits) - Understand concurrency and queue limits
***
## Account Access
Set up your account and manage API credentials.
* [Account Setup](/account-access/account-setup) - Get started with your Wiza account
* [Purchasing API Credits](/account-access/purchasing-api-credits) - Learn how to purchase and manage credits
* [Generate API Key](/account-access/generate-api-key) - Create your API key for authentication
* [API Key Management](/account-access/api-key-management) - Manage and rotate your API keys
***
## Using the API
Learn how to make requests and get the data you need.
* [Authorization](/using-the-api/authorization) - Authenticate with Bearer token
* [Recommended Inputs](/using-the-api/recommended-inputs) - Best practices for input data
* [Find Mobile Phone Numbers](/using-the-api/find-mobile-phone-number) - Retrieve mobile phone numbers
* [Find Email Addresses](/using-the-api/find-email-addresses) - Find work and personal emails
* [Find Profile Details](/using-the-api/find-linkedin-profile-information) - Get detailed Profile Details
* [Bulk Enrichment](/using-the-api/bulk-enrichment) - Enrich multiple contacts at once
* [Credit Deduction Behavior](/using-the-api/credit-deduction-behavior) - Understand how credits are consumed
* [Status Codes & Errors](/using-the-api/status-codes-and-errors) - Handle API responses and errors
***
## API Reference
Explore the API endpoints.
* [Start Individual Reveal](/api-reference/individual-reveals/start-individual-reveal) - Enrich a contact
* [Get Individual Reveal](/api-reference/individual-reveals/get-individual-reveal) - Retrieve enrichment results
* [Get Credits](/api-reference/credits/get-credits) - Check your credit balance
* [Prospect Search](/api-reference/prospect/prospect-search) - Find prospects matching your filters
* [Company Enrichment](/api-reference/company-enrichment/company-enrichment) - Enrich company data
**Legacy Endpoints**
* [Create List](/api-reference/lists/create-list) - Create a list of people to enrich
* [Get List](/api-reference/lists/get-list) - Get list status and details
* [Get List Contacts](/api-reference/lists/get-list-contacts) - Retrieve enriched contacts from a list
* [Create Prospect List](/api-reference/prospect-lists/create-prospect-list) - Create a list from prospect search
* [Continue Prospect Search](/api-reference/prospect-lists/continue-prospect-search) - Continue a previous search
***
## Integrations
Connect Wiza with your favorite tools.
* [Clay](/integrations/clay) - Use Wiza within Clay for enrichment workflows
* [n8n](/integrations/n8n) - Use Wiza within n8n workflows for contact enrichment
* [Apollo.io](/integrations/apollo) - Use Wiza with Apollo.io waterfall enrichment
# Apollo.io
Source: https://docs.wiza.co/integrations/apollo
Use Wiza with Apollo.io waterfall enrichment
Wiza can be used in Apollo.io's waterfall enrichment feature by connecting your Wiza API key. Apollo.io's waterfall feature enables users to add and prioritize Wiza as a primary data source when enriching lists built with emails and phone numbers. These enrichments use Wiza API credits, which can be purchased and monitored in your Wiza account.
## How to use Wiza in Apollo.io
You must be on a paid Apollo.io plan to use their waterfall enrichment feature.
1. Sign in to Apollo.io and build or select a saved list.
2. Hover over the icon featured in the "Emails" and "Phone Numbers" columns to open the default waterfall preview.
3. Then, click on the gear setting in upper right of the waterfall preview.
4. Under Enrichment configuration, select the **Add** button, choose **Wiza** from the providers, and confirm by clicking **add sources**.
5. With Wiza now in your waterfall, hover over the label and click the key icon to open an Add API key modal.
6. In the Add API key modal, name your API key, paste your API key, and click **save**.
7. You've now successfully added Wiza to your Apollo.io enrichment waterfall, connected your Wiza API key, and can position it as you choose.
## API Endpoints
* [Start Individual Reveal](/api-reference/individual-reveals/start-individual-reveal) - Enrich a contact
* [Get Individual Reveal](/api-reference/individual-reveals/get-individual-reveal) - Retrieve enrichment results
* [Get Credits](/api-reference/credits/get-credits) - Check your credit balance
* [Company Enrichment](/api-reference/company-enrichment/company-enrichment) - Enrich company data
# Clay
Source: https://docs.wiza.co/integrations/clay
Use Wiza within Clay for enrichment workflows
Wiza can be used in Clay by connecting your Wiza API key. Clay workflows can then run Wiza enrichments for emails, mobile phone numbers, Profile Details, and company information. These enrichments consume Wiza API credits, which can be purchased and monitored in your Wiza account.
Enrichments follow the same usage limits and credit deduction rules as direct API requests.
Visit [https://university.clay.com/docs/wiza-integration-overview](https://university.clay.com/docs/wiza-integration-overview) for more details.
# n8n
Source: https://docs.wiza.co/integrations/n8n
Use Wiza within n8n workflows for contact enrichment
Wiza can be used in n8n by using the official Wiza node and inputting your Wiza API key. Wiza's node enables n8n users to find email addresses, mobile phone numbers, and Profile Details. These enrichments consume Wiza API credits, which can be purchased and monitored in your Wiza account settings > API.
## How to use Wiza in n8n
1. Sign in to n8n, open the editor, and click **+** in the top right to open the Nodes panel
2. Search for **Wiza** using the search bar. Look for the version marked by a badge image. Then, select **install**.
3. Once Wiza is installed, just drag, drop, and connect it like any other node in a workflow.
See the [Wiza n8n Integration page](https://n8n.io/integrations/wiza/) for more details, Wiza + n8n workflow templates, and to get started.
## API Endpoints
* [Start Individual Reveal](/api-reference/individual-reveals/start-individual-reveal) - Enrich a contact
* [Get Individual Reveal](/api-reference/individual-reveals/get-individual-reveal) - Retrieve enrichment results
* [Get Credits](/api-reference/credits/get-credits) - Check your credit balance
* [Company Enrichment](/api-reference/company-enrichment/company-enrichment) - Enrich company data
# Data Dictionary
Source: https://docs.wiza.co/overview/data-dictionary
Understanding the data structure and fields
## Contact Data
| Field | Description |
| ------------------- | -------------------------- |
| Mobile Phone Number | Direct mobile number |
| Work Email | Professional email address |
| Personal Email | Personal email address |
## Profile Details
| Field | Description |
| --------------------------- | ----------------------------- |
| Name | Contact's full name |
| Company | Current company name |
| Job Title | Current job title |
| Location | Geographic location |
| Profile URL | Profile URL |
| Contact Profile Picture URL | Contact's profile image |
| Company Profile Picture URL | Company logo image |
| Headline | Profile Headline |
| Bio | Profile summary/about section |
| Work History | Past jobs and positions |
| Job Responsibilities | Current role responsibilities |
| Months at Current Company | Tenure at company |
| Months at Current Role | Tenure in current position |
| Premium account status | Premium account status |
| Open To Work | Job seeking status |
| Skills | Listed skills |
| Languages | Languages spoken |
| Certifications | Professional certifications |
| Education | Educational background |
## Company Details
| Field | Description |
| ----------------------- | --------------------------------- |
| Company Domain | Website domain |
| Company Profile URL | Company Profile URL |
| Company Industry | Primary industry |
| Company Sub-Industry | Secondary industry classification |
| Company Headcount | Number of employees |
| Company Founding Year | Year established |
| Company Revenue | Annual revenue |
| Company Funding | Total funding raised |
| Company Public/Private | Public or private status |
| Company Twitter | Twitter handle |
| Company Facebook | Facebook page |
| Company Description | Company overview |
| Last Funding | Most recent funding date |
| Round Type | Type of last funding round |
| Last Funding Round Size | Amount of last funding |
| Company HQ Location | Headquarters location |
# Introduction
Source: https://docs.wiza.co/overview/introduction
Welcome to Wiza API documentation
Welcome to Wiza's API! We are designed for developers who prioritize data accuracy. You can find emails, phone numbers, and contact details. Our APIs are widely used for the following:
* **Build custom enrichment workflows**
* **Power data enrichment products and applications**
* **Use your own Wiza API key within supported integration partners**
# Key Functionality
Source: https://docs.wiza.co/overview/key-functionality
Key features and capabilities of the Wiza API
The Wiza API provides powerful capabilities for finding and verifying professional contact information:
* **Find work and personal email addresses**
* **Find mobile phone numbers**
* **Find Profile Details**
* **Find company-level details**
# Usage Limits
Source: https://docs.wiza.co/overview/usage-limits
API rate limits and usage guidelines
The following behavior applies specifically to the **Start Individual Reveal API** (`https://wiza.co/api/individual_reveals`):
## Concurrency Limit
You can send requests to Wiza in batches, each of which requires a brief real-time processing step to find and verify contact data in real-time. The concurrency limit defines how many requests can be processed in parallel at any moment. When that limit is reached, additional requests queue and automatically begin processing as soon as an active request completes.
| Plan | Concurrency Limit |
| -------------- | ------------------- |
| Starter API | 5 |
| Enterprise API | 15+ (scales higher) |
**Example:** If your concurrency limit is 15 and you send 50 requests at once, 15 requests will begin processing immediately. The remaining 35 requests are placed in the queue. As each active request completes and returns a response, the next queued request starts processing automatically.
## Queue Limit
A queue limit defines how many requests can be held waiting when all concurrency slots are currently in use. It is set to **200× your concurrency limit**, and once the queue is full, additional requests will return errors until capacity becomes available.
**Example:** If your concurrency limit is 15, your queue limit is 3,000.
# Authorization
Source: https://docs.wiza.co/using-the-api/authorization
Authenticate your API requests with Bearer token
All Wiza API requests require authentication using a Bearer token. Include your API key in the `Authorization` header of every request.
## Header Format
```
Authorization: Bearer YOUR_API_KEY
```
## Examples
```bash curl theme={"dark"}
curl -X POST https://wiza.co/api/individual_reveals \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"individual_reveal": {
"profile_url": "https://www.linkedin.com/in/example/"
},
"enrichment_level": "partial"
}'
```
```javascript JavaScript theme={"dark"}
const apiKey = "YOUR_API_KEY";
const response = await fetch("https://wiza.co/api/individual_reveals", {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
individual_reveal: {
profile_url: "https://www.linkedin.com/in/example/"
},
enrichment_level: "partial"
})
});
const data = await response.json();
console.log(data);
```
```python Python theme={"dark"}
import requests
api_key = "YOUR_API_KEY"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
payload = {
"individual_reveal": {
"profile_url": "https://www.linkedin.com/in/example/"
},
"enrichment_level": "partial"
}
response = requests.post(
"https://wiza.co/api/individual_reveals",
headers=headers,
json=payload
)
print(response.json())
```
```ruby Ruby theme={"dark"}
require "uri"
require "json"
require "net/http"
api_key = "YOUR_API_KEY"
url = URI("https://wiza.co/api/individual_reveals")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer #{api_key}"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
individual_reveal: {
profile_url: "https://www.linkedin.com/in/example/"
},
enrichment_level: "partial"
})
response = https.request(request)
puts response.read_body
```
## Error Responses
### 401 Unauthorized
Returned when the API key is missing, invalid, or expired.
```json theme={"dark"}
{
"status": {
"code": 401,
"message": "Unauthorized"
}
}
```
**Common causes:**
* Missing `Authorization` header
* Invalid API key format (must be `Bearer YOUR_API_KEY`)
* API key has been disabled
* API key does not exist
## Related
* [Generate an API Key](/account-access/generate-api-key) - Create your API key
* [API Key Management](/account-access/api-key-management) - Manage and rotate keys
* [Status Codes & Errors](/using-the-api/status-codes-and-errors) - Full error reference
# Autocomplete Filters
Source: https://docs.wiza.co/using-the-api/autocomplete
Find the exact location and technology values accepted by Prospect search filters
Use the Meta API autocomplete endpoints to turn a user's text into the exact values required by the Prospect API. Both endpoints require your API key in the `Authorization` header and a query of at least three characters.
## Location autocomplete
`GET https://wiza.co/api/meta/location_autocomplete?query=tor`
Searches the available location catalog and returns up to 10 matching locations and regional groups. Each result includes:
* `key` — the exact location value to send in a search filter
* `bucket` — the matching location boundary: `city`, `state`, `country`, `continent`, or `group`
* `count` — the number of matching records in the catalog
```json theme={"dark"}
{
"status": 200,
"data": [
{
"key": "Toronto, Ontario, Canada",
"bucket": "city",
"count": 1234
}
]
}
```
Copy the result's `key` to `v` and its `bucket` to `b` in the [`location` or `company_location` Prospect filter](/api-reference/prospect/prospect-search). For example:
```json theme={"dark"}
{
"company_location": [
{
"v": "Toronto, Ontario, Canada",
"b": "city"
}
]
}
```
## Technographics autocomplete
`GET https://wiza.co/api/meta/technology_autocomplete?query=aws`
Searches the technology catalog and returns up to 10 technologies that match a technology name or slug. Each result includes:
* `name` — the technology name to display to your user
* `slug` — the exact value accepted by the Prospect API `technologies` filter
```json theme={"dark"}
{
"status": {
"code": 200,
"message": ""
},
"data": [
{
"slug": "amazon-web-services",
"name": "Amazon Web Services (AWS)"
}
]
}
```
Copy the result's `slug` to `v` in the [`technologies` Prospect filter](/api-reference/prospect/prospect-search). Add `s: "e"` when you want to exclude a technology:
```json theme={"dark"}
{
"technologies": [
{
"v": "amazon-web-services"
},
{
"v": "salesforce",
"s": "e"
}
]
}
```
# Bulk Enrichment
Source: https://docs.wiza.co/using-the-api/bulk-enrichment
Enrich multiple contacts at once
Use the Start Individual Reveal endpoint (`https://wiza.co/api/individual_reveals`) to submit requests in batches. Requests will process in parallel in accordance with your [concurrency limit](/overview/usage-limits#concurrency-limit). Requests beyond the limit queue automatically and are processed as slots free up, enabling efficient bulk enrichment.
# Credit Deduction Behavior
Source: https://docs.wiza.co/using-the-api/credit-deduction-behavior
Understand how credits are consumed
Credits are pre-paid in bulk and deducted only when data is successfully returned:
| Data Type | Enrichment Level | Credits Deducted |
| --------------- | ----------------------------------------- | ---------------------------------------------------------- |
| Phones | `"enrichment_level": "phone"` or `"full"` | 5 credits if at least one phone number is returned |
| Emails | `"enrichment_level": "email"` or `"full"` | 2 credits if at least one "valid" marked email is returned |
| Profile Details | `"enrichment_level": "none"` | 1 credit if a Profile URL is found and matched |
## Confirming Credit Deductions
After making a POST request and retrieving results via the GET endpoint (`https://wiza.co/api/individual_reveals/{id}`), you can confirm the credits that were deducted in the response under the `credits` object.
The relevant fields include:
* **api\_credits.total** – Total API credits deducted by this request
* **api\_credits.email\_credits** – Number of credits deducted due to emails found
* **api\_credits.phone\_credits** – Number of credits deducted due to phones found
* **api\_credits.scrape\_credits** – Number of credits deducted when Profile URLs are successfully matched. Unmatched Profile URLs are not charged.
**Sample GET Response Snippet:**
```json theme={"dark"}
"credits": {
"api_credits": {
"total": 5,
"email_credits": 0,
"phone_credits": 5,
"scrape_credits": 0
}
}
```
# Find Email Addresses
Source: https://docs.wiza.co/using-the-api/find-email-addresses
Find work and personal email addresses
Wiza may return one work email and one personal email per profile.
***
## Step 1: Start Individual Reveal
**Endpoint:** `https://wiza.co/api/individual_reveals`
Send a POST request with your API key, setting `"enrichment_level": "partial"` to retrieve emails. Use the `email_options` object to specify whether you want to find work emails, personal emails, or both. The response will include an `id`, which you will use in Step 2.
* `"accept_work": true` → include work emails
* `"accept_personal": true` → include personal emails
* Setting a value to `false` indicates that you do not want to retrieve that type of email.
Requests for work emails may take 0 - 380 seconds to process, with an average response time of \~25 seconds. Requests for personal emails may take 0 - 15 seconds to process, with an average response time of \~4 seconds.
**Sample Request Body:**
```json theme={"dark"}
{
"individual_reveal": {
"profile_url": "https://www.linkedin.com/in/stephen-hakami-5babb21b0/"
},
"enrichment_level": "partial",
"email_options": {
"accept_work": true,
"accept_personal": false
}
}
```
***
## Step 2: Retrieve Reveal Results
**Endpoint:** `GET https://wiza.co/api/individual_reveals/{id}`
Use the `id` returned from Step 1 to access the enriched data. For best results, parse `email`, `email_type`, and `email_status` from the emails array. Multiple emails may be returned per profile.
Alternatively, if a webhook is configured, the completed reveal will be delivered automatically.
# Find Profile Details
Source: https://docs.wiza.co/using-the-api/find-linkedin-profile-information
Get detailed Profile Details
## Step 1: Start Individual Reveal
**Endpoint:** `POST https://wiza.co/api/individual_reveals`
Send a POST request with your API key and set `"enrichment_level": "none"` to retrieve Profile Details.
Wiza retrieves this data in real-time and returns the fields listed under [Profile Details](/overview/data-dictionary#profile-details) and [Company Details](/overview/data-dictionary#company-details) in the Data Dictionary.
Not all data points are included by default. To include additional Profile Details, go to **Settings → Data & Export → Advanced Columns** and enable the desired fields.
The request may take 0 - 15 seconds to process, with an average response time of \~5 seconds. The response will include an `id`, which you will use in Step 2 to retrieve the enriched Profile Details.
## Step 2: Retrieve Profile Details
**Endpoint:** `GET https://wiza.co/api/individual_reveals/{id}`
Use the `id` returned from Step 1 to access the enriched data. Profile Details and company details associated with the profile will be returned.
Alternatively, if a webhook is configured, the completed reveal will be delivered automatically.
# Find Mobile Phone Number
Source: https://docs.wiza.co/using-the-api/find-mobile-phone-number
Retrieve mobile phone numbers for contacts
Wiza may return up to three mobile numbers per profile. For highest quality results, parse the following fields:
* **phone\_number** – Primary mobile number, highest quality in E.164 format.
* **number\_pretty** – Human-readable format (e.g., +1 (123) 456-7890).
* **number** – Raw number from the phones array, in E.164 format.
- In the phones array, `"type": "mobile"` and `"type": "other"` are all mobile numbers
- All numbers in the phones array (up to three) can be parsed
- Do not rely solely on `mobile_phone`
***
## Step 1: Start Individual Reveal
**Endpoint:** `https://wiza.co/api/individual_reveals`
Send a POST request with your API key and `"enrichment_level": "phone"`. The response will include an `id`, which you will use in Step 2.
The request may take 0-15 seconds to process, with an average response time of \~4 seconds.
**Sample Request Body:**
```json theme={"dark"}
{
"individual_reveal": {
"profile_url": "https://www.linkedin.com/in/stephen-hakami-5babb21b0/"
},
"enrichment_level": "phone"
}
```
***
## Step 2: Retrieve Reveal Results
**Endpoint:** `GET https://wiza.co/api/individual_reveals/{id}`
Use the `id` returned from Step 1 to access the enriched data. For best results, parse `phone_number`, `number_pretty`, or `number`. Wiza may return up to three mobile numbers.
Alternatively, if a webhook is configured, the completed reveal will be delivered automatically.
**Sample 1 Response Snippet: One Mobile Number Found**
```json theme={"dark"}
{
"mobile_phone": null,
"phone_number": "+13133383662",
"phone_status": "found",
"phones": [
{
"number": "+13133383662",
"number_pretty": "+1 (313) 338-3662",
"type": "other"
}
]
}
```
**Sample 2 Response Snippet: Multiple Mobile Numbers Found**
```json theme={"dark"}
{
"mobile_phone": "+14155552672",
"phone_number": "+14155552672",
"phone_status": "found",
"phones": [
{
"number": "+14155552672",
"number_pretty": "+1 (415) 555-2672",
"type": "mobile"
},
{
"number": "+13105559874",
"number_pretty": "+1 (310) 555-9874",
"type": "other"
},
{
"number": "+14085551254",
"number_pretty": "+1 (408) 555-1254",
"type": "other"
}
]
}
```
# Recommended Inputs
Source: https://docs.wiza.co/using-the-api/recommended-inputs
Best practices for input data to maximize results
For the `/api/individual_reveals` endpoint, provide **one of** the following input options per request. Different inputs offer varying levels of coverage and accuracy and are listed below from highest to lowest.
1. **Profile URL** **(strongly recommended)** - Provides the highest performing results
2. **Full name + company domain and/or company name** - Including a company domain improves match accuracy, as domains are unique while company names may have duplicates. This option provides the next best-performing results.
3. **Email address** - Use only if other input options are unavailable
***
## Payload Examples
### Option 1: Profile URL
```json theme={"dark"}
{
"individual_reveal": {
"profile_url": "https://www.linkedin.com/in/stephen-hakami-5babb21b0/"
},
"enrichment_level": "partial"
}
```
### Option 2: Full Name + Company Domain
```json theme={"dark"}
{
"individual_reveal": {
"full_name": "Stephen Hakami",
"domain": "wiza.co"
},
"enrichment_level": "partial"
}
```
### Option 2b: Full Name + Company Name
```json theme={"dark"}
{
"individual_reveal": {
"full_name": "Stephen Hakami",
"company": "Wiza"
},
"enrichment_level": "partial"
}
```
### Option 3: Email Address
```json theme={"dark"}
{
"individual_reveal": {
"email": "stephen@wiza.co"
},
"enrichment_level": "partial"
}
```
# Status Codes & Errors
Source: https://docs.wiza.co/using-the-api/status-codes-and-errors
Handle API responses and errors
Not all API status codes are currently documented by Wiza. This documentation contains the most common codes. If you encounter a status that does not make sense, contact Wiza's support team for further assistance.
## HTTP Status Codes
| Status Code | Description |
| ----------- | ---------------------------------------------------- |
| 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 Status Code
Billing issues return a `200` response, but the reveal does not run. The record is marked as `status: "failed"` with `fail_error: "billing_issue"`, indicating processing was blocked due to missing credits or an unresolved payment.
# Webhooks
Source: https://docs.wiza.co/using-the-api/webhooks
Receive real-time notifications when enrichment requests complete
Wiza sends webhook notifications to your server when enrichment requests complete. This lets you process results asynchronously without polling the API.
When a request finishes (or fails), Wiza sends a `POST` request to your configured URL with the enrichment results.
***
## Setting Up Your Webhook URL
Configure your default webhook URL in [Settings → API](https://wiza.co/app/settings/api). This URL applies to all API requests made with that key.
You can also enable **Send All Callbacks** to receive webhooks for all enrichment activity on your account, not just requests made through the API.
Your webhook endpoint must be publicly accessible and return a `200` status code to acknowledge receipt.
***
## Handling Webhook Requests
Respond quickly with a `200` status code to acknowledge receipt. If your processing takes time, accept the webhook first and handle the work asynchronously in a background job.
Use `status.code` to check for success (`200`) or failure (`400`). For the full response schema, see the [Individual Reveal](/using-the-api/find-email-addresses#step-2-retrieve-reveal-results) documentation.
```javascript JavaScript theme={"dark"}
app.post('/webhook', (req, res) => {
// Acknowledge receipt immediately
res.status(200).send('OK');
// Process asynchronously
const { status, data } = req.body;
if (status.code === 200) {
processReveal(data);
}
});
```
```python Python theme={"dark"}
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def wiza_webhook():
payload = request.get_json()
status = payload.get('status', {})
data = payload.get('data')
if status.get('code') == 200:
process_reveal(data)
# Acknowledge receipt immediately
return jsonify({'status': 'ok'}), 200
```
```ruby Ruby theme={"dark"}
post '/webhook' do
payload = JSON.parse(request.body.read)
payload_status = payload['status']
data = payload['data']
if payload_status['code'] == 200
process_reveal(data)
end
# Acknowledge receipt immediately
status 200
{ status: 'ok' }.to_json
end
```
***
## Overriding the Webhook URL Per Request
You can override the default webhook URL on a per-request basis by including a `callback_url` parameter in your **Start Individual Reveal** request.
```json theme={"dark"}
{
"individual_reveal": {
"profile_url": "https://www.linkedin.com/in/stephen-hakami-5babb21b0/"
},
"enrichment_level": "partial",
"callback_url": "https://your-server.com/webhook"
}
```
***
## Webhook Payload
**Endpoint:** `POST {your_webhook_url}`
Wiza sends a webhook when an Individual Reveal completes or fails. The request is a `POST` with a `Content-Type: application/json` header sent to your configured URL or the `callback_url` specified in the request. The `data` object contains the same enrichment results as the corresponding GET endpoint.
**Individual Reveal Payload:**
```json theme={"dark"}
{
"status": {
"code": 200,
"message": "Single reveal finished"
},
"type": "individual_reveal",
"data": {
"id": 123456,
"status": "finished",
"is_complete": true,
"name": "Stephen Hakami",
"company": "Wiza",
"enrichment_level": "partial",
"linkedin_profile_url": "https://www.linkedin.com/in/stephen-hakami-5babb21b0/",
"title": "Founder, Chief Executive Officer",
"location": "Toronto, Ontario, Canada",
"email": "stephen@wiza.co",
"email_type": "work",
"email_status": "valid",
"emails": [
{
"email": "stephen@wiza.co",
"email_type": "work",
"email_status": "valid"
}
],
"credits": {
"email_credits": 1,
"phone_credits": 0,
"export_credits": 0,
"api_credits": {
"total": 2,
"email_credits": 2,
"phone_credits": 0,
"scrape_credits": 1
}
}
}
}
```
**Failed Request Payload:**
When a request fails, the `status.code` will be `400`. The `data` object contains the same fields as a successful response, with a `fail_error` field indicating the failure reason.
```json theme={"dark"}
{
"status": {
"code": 400,
"message": "Single reveal failed"
},
"type": "individual_reveal",
"data": {
"id": 123456,
"status": "failed",
"fail_error": "..."
}
}
```
***
## Verifying Webhook Signatures
Webhook requests include an `x-auth-key` header containing a SHA256 hash of your API key. Use this to verify the request originated from Wiza.
```javascript JavaScript theme={"dark"}
const crypto = require('crypto');
function verifyWebhook(request, apiKey) {
const receivedHash = request.headers['x-auth-key'];
const expectedHash = crypto
.createHash('sha256')
.update(apiKey)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(receivedHash),
Buffer.from(expectedHash)
);
}
```
```python Python theme={"dark"}
import hashlib
import hmac
def verify_webhook(headers, api_key):
received_hash = headers.get('x-auth-key')
expected_hash = hashlib.sha256(api_key.encode()).hexdigest()
return hmac.compare_digest(received_hash, expected_hash)
```
```ruby Ruby theme={"dark"}
require 'digest'
require 'rack/utils'
def verify_webhook(request, api_key)
received_hash = request.headers['x-auth-key']
expected_hash = Digest::SHA256.hexdigest(api_key)
Rack::Utils.secure_compare(received_hash, expected_hash)
end
```
***
## Retry Behavior
If your webhook endpoint returns a non-2xx response, Wiza will retry up to 3 times. Ensure your endpoint is available and returns a `200` status code to acknowledge receipt.
If a webhook consistently fails (returns 404 or 403), Wiza will stop retrying for that request.
***
## Related
* [Status Codes & Errors](/using-the-api/status-codes-and-errors) — Handle API responses
* [Authorization](/using-the-api/authorization) — Authenticate your API requests