{"info":{"_postman_id":"84e52e3e-e6e9-4a84-9fa6-84b8ae4e9692","name":"BriteVerify API Documentation","description":"

Authorization

API key is required to access BriteVerify API:

Log into your account and navigate to the API Keys tab.
Click on 'Generate New Key' and provide a key name. Key names don't have any functional impact, but should be meaningful, such that a key name would explain its purpose, which is particularly handy when multiple keys are procured.
Select a key type - select Client-side type for keys used in a client-side(browser) implementation, otherwise select Server-side. See Public Keys ↗ for more information about client side initiated real time validations.
Once a key is created, it is immediately available for use and should appear in the list.

API Key Best Practices

API keys are sensitive and should be handled as passwords, since they provide access account data as well as the ability to perform verifications. Therefore, API keys should be stored securely and shared on as-needed basis only.

When a key is compromised or when there is a suspicion of a key being abused, that key must be immediately deactivated and replaced:

Navigate to the API Keys tab in your BriteVerify account.
Locate the key in question and click on the Actions gear, then click 'Deactivate'. This action cannot be undone.
Generate a new key and replace the old one in your code.

Rate Limits and Performance

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Endpoint	Rate Limits	Processing Speeds	Notes
Real-time Single Transaction API	500 verifications per key, per minute. Applies to both server-side and client-side (public) keys. 25 verifications per client IP address, per minute. Applies to client-side (public) keys only. Both constraints are enforced.	Average response time: 500 ms	When rate limit is exceeded, server will respond with HTTP Code `429`. Integrating applications should be implemented to avoid reaching throttling limits. If you believe your transactional traffic will be greater than 500 requests per key, per minute, contact Validity Support team for additional guidance.
Bulk API	100K Emails per page 1M Email addresses per job (or 20 pages of 50K)	4,000 verifications per minute	This is an average based upon performance achieved by 95% of customers. Actual speeds can vary depending on network load, time of day, domain response times, and quality of addresses being verified.

HTTP Response Codes

200 Success
400 Bad Request (indicates invalid or missing query and/or body parameters)
401 Unauthorized (no valid API key provided)
403 Forbidden (indicates lack of access to the performed operation)
404 Not Found (indicates invalid parameters or missing API endpoint)
422 Unprocessable Entity (indicates invalid data or a request that violates business rules)
429 Too Many Requests (Rate limit have been exceeded, retry after some time)
500 Internal Server Error (An unexpected error on Validity BriteVerify side)

Email Responses

Status Field

The status field will return one of the following:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Explanation	Suggested Action
`valid`	The email address is a valid account.	Safe to mail
`invalid`	The email address is invalid. See Secondary Statuses section below for more details.	Do not mail
`risky`	The email address may be valid, but certain conditions suggest potential delivery issues or poor performance. This includes addresses associated with full inboxes, disposable or role-based accounts, or domains that return uncertain responses (e.g., accept-all or temporary errors). The specific reason for this status is provided in the status_detail field, see the table below for more information.	Proceed with caution. These emails might still accept messages, but they are more likely to bounce or underperform. If you decide to mail them, consider: – Monitor bounce rates closely. – Send gradually to reduce deliverability risk. – Avoid mailing if your ESP’s bounce tolerance is low (e.g., ≤5%). – Regularly revalidate these addresses before future sends.

Status Detail

For non-valid email results, i.e. addresses with any status other than valid, the reason for invalidity is returned in two different fields depending on the API endpoint:

Possible values for non-valid emails:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

status_detail	Explanation
email_address_invalid	Email address format is incorrect. For example, james0uwerwe#com is not in the correct email format of inbox@domain.com. Many of these can be prevented by applying simple regular expression to data prior to verification.
email_domain_invalid	Email address is associated with a domain that doesn't exist. For example, briteeeeverify.com is not a real domain capable of sending and receiving emails. So inbox@briteeeeverify.com is an invalid email since it pertains to a domain that does not exist.
email_account_invalid	The email account (the inbox) does not exist at the given domain. For example, not-an-inbox@briteverify.com results in a secondary status of email_account_invalid.
mailbox_full	The inbox for this email account is full and cannot accept new incoming mail. Sending to this email address will generate a soft bounce. While soft bounces are typically not penalized harshly, routinely sending to an email address that bounces can negatively impact your sender reputation. Consider holding sends to this address until this status is cleared.
disposable	Email address is disposable and the inbox will self-destruct. Disposable addresses are created to be valid temporarily so that their owners can sign up for promotions or services without using a primary address. Disposable addresses will not yield value and typically just take up space in your database.
temporary_error	This email is Unknown status because the email provider indicated a temporary error. Try to validate these email addresses again later.
blocked	This email is Unknown because the email provider blocked the request to validate this email without providing further information. Keep these email addresses but monitor delivery closely.
not_enough_data	This email is Unknown because expected response was not received from this email domain. Exclude this email from your list as it’s likely invalid.

Enrichment Attribute

This field provides additional context about the verified email address, indicating specific characteristics or detected conditions.

Multiple enrichment values may be returned for the same email (e.g., [\"typo\", \"corrected\"]).

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Enrichment	Explanation
duplicated	The email address has already appeared earlier in the same verification request.
typo	A typo was detected in the email address.
corrected	The email address was automatically corrected
disposable	The domain belongs to a disposable email provider.
role address	The email represents a role-based or generic account (e.g., `info@`, `support@`, `sales@`).
alias	The address appears to be an alias or forwarding address (e.g., Gmail “plus addressing” like `user+promo@gmail.com`).
freemail	The domain belongs to a free, public email provider (e.g., Gmail, Yahoo, Outlook).
education	The domain is associated with an educational institution.
government	The domain is associated with a government entity.
military	The domain is associated with a military organization.

Optional Attributes

If Typo Correction is enabled for your account, the API response may include up to three additional top-level attributes when the original email is determined to be invalid.

These fields provide details about the automatically corrected version of the email address and its verification results.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Attribute	Explanation
corrected_email	The corrected version of the email address, generated when a likely typo is detected in the domain or local part (e.g., user@gmial.com → user@gmail.com).
corrected_email_status	The verification status of the corrected email. This field follows the same possible values listed in the Status table above.
corrected_email_status_detail	A more specific reason describing the status of the corrected email, using the same set of values defined in the Status Detail table above.

Phone Responses

Status and Errors Fields

The status field returns valid, invalid, or unknown. If the phone number is invalid, an error message is included in the errors object explaining the reason.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Error Code	Explanation
valid	-	-
invalid	invalid_phone_number	The provided number does not exist.
invalid	blank_phone_number	The phone number field is blank. This could be due to improper formatting.
invalid	invalid_format	The number provided has insufficient or inaccurate information.
invalid	invalid_prefix	Unable to verify the phone prefix or first 7 digits.
unknown	-	-

Addresses Responses

Status and Errors Fields

The status field returns valid, invalid, or unknown. If the address is invalid, an error message is included in the errors object explaining the reason.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Error Code	Explanation
valid	-	-
invalid	suite_invalid_missing	While the street address is valid, the suite/apartment is missing or invalid.
invalid	multiple_match	Two or more possible addresses are matched and so unable to choose one over the other.
invalid	missing_minimum_inputs	Missing minimum inputs to verify address.
invalid	zip_code_invalid	The address could not be verified based on the postal code provided.
invalid	unknown_street	Could not conclusively locate the input street to its unique street name.
invalid	directionals_invalid	Directional information did not match with the suffix provided (Ave, St, Blvd)
invalid	non_deliverable_address	Address cannot be delivered to.
invalid	suite_invalid	While the street address is valid, the suite/apartment provided is invalid.
invalid	suite_missing	While the street address is valid, the suite/apartment provided is required.
invalid	street_number_invalid	The building or house number is invalid.
invalid	street_number_missing	The building or house number is required.
invalid	box_number_invalid	The PO box number is invalid.
invalid	box_number_missing	The PO box number is required.
invalid	pmb_required	The Private mailbox number is missing.
unknown	-	-

","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"11411276","collectionId":"84e52e3e-e6e9-4a84-9fa6-84b8ae4e9692","publishedId":"SzmjyuQH","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"37ACF0"},"publishDate":"2020-08-20T16:16:56.000Z"},"item":[{"name":"Real-time Single Transaction","item":[{"name":"Account Information","item":[{"name":"Credits","id":"eaec9a59-e529-4cb2-a358-1ee4be3ad1d7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"disabled":false,"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"ApiKey: {{api_key}}"}],"body":{"mode":"raw","raw":""},"url":"{{rt_base_url}}/api/v1/accounts/credits","description":"

This endpoint will return your account credit balance and credits in reserve*, current as of the recorded_on timestamp.

*Credits in reserve are those being held for currently processing list uploads (via manual upload or bulk api upload)

\n","urlObject":{"path":["api","v1","accounts","credits"],"host":["{{rt_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"b67f51e8-cbb7-4358-bce5-d7b9758e3a6b","name":"Credit Balance","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: {{api_key}}"}],"url":"{{rt_base_url}}/api/v1/accounts/credits"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"credits\": 2165,\n \"credits_in_reserve\": 500,\n \"recorded_on\": \"2021-07-27T21:10:10.000+0000\"\n}"}],"_postman_id":"eaec9a59-e529-4cb2-a358-1ee4be3ad1d7"}],"id":"faffaa5e-5fea-40b3-bcf5-ae8650cb9c0c","_postman_id":"faffaa5e-5fea-40b3-bcf5-ae8650cb9c0c","description":""},{"name":"Client-side API Key","item":[{"name":"Email, Phone, and Address","event":[{"listen":"test","script":{"id":"0896cfec-45a9-4e3b-b696-e33e052cb07f","exec":[""],"type":"text/javascript"}}],"id":"a7246384-e91e-48a9-8aed-7b71cb74dd42","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","value":"ApiKey: {{api_key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"email\": \"sales@validity.com\",\n \"phone\": \"18009618205\",\n \"address\": {\n \t\"address1\": \"4010 Boy Scout Boulevard, Suite 1100\",\n \t\"city\": \"Tampa\",\n \t\"state\": \"FL\",\n \t\"zip\": \"33607\"\n }\n}"},"url":"{{rt_base_url}}/api/public/v4/fullverify","description":"

You must provide at least one of the following fields in your request: email, phone, or address.

You can include just one, two, or all three, depending on your use case.

Phone number and mailing address verification available for the United States and Canada only at this time.

\n","urlObject":{"path":["api","public","v4","fullverify"],"host":["{{rt_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"9bfc716e-fa52-4f12-8f87-92e3ebc5bf23","name":"Valid Email, Valid Phone, and Valid Address","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: api-key-here"}],"body":{"mode":"raw","raw":"{\n \"email\": \"sales@validity.com\",\n \"phone\": \"18009618205\",\n \"address\": {\n \t\"address1\": \"4010 Boy Scout Boulevard, Suite 1100\",\n \t\"city\": \"Tampa\",\n \t\"state\": \"FL\",\n \t\"zip\": \"33607\"\n }\n}"},"url":"https://bpi.briteverify.com/api/public/v4/fullverify"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Thu, 14 May 2020 20:00:27 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"ETag","value":"W/\"4ff16a9e3e06a519c6ece4811dad5f18\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"X-Request-Id","value":"994beec2-0cc4-40cb-afff-910ae8010ec2"},{"key":"X-Runtime","value":"2.399402"}],"cookie":[],"responseTime":null,"body":"{\n \"email\": {\n \"address\": \"sales@validity.com\",\n \"account\": \"sales\",\n \"domain\": \"validity.com\",\n \"status\": \"valid\",\n \"status_detail\": null,\n \"enrichment\": []\n },\n \"phone\": {\n \"number\": \"18009618205\",\n \"service_type\": \"land\",\n \"phone_location\": null,\n \"status\": \"valid\",\n \"errors\": []\n },\n \"address\": {\n \"address1\": \"4010 W Boy Scout Blvd Ste 1100\",\n \"address2\": \" \",\n \"city\": \"Tampa\",\n \"state\": \"FL\",\n \"zip\": \"33607-5796\",\n \"status\": \"valid\",\n \"errors\": [],\n \"corrected\": true\n },\n \"duration\": 0.392828819\n}"}],"_postman_id":"a7246384-e91e-48a9-8aed-7b71cb74dd42"}],"id":"0cb13e0a-4725-40ff-bdcd-b9eda46e0dc6","description":"

This endpoints assumes use of Client-side API keys.

Examples of Client-side use cases:

Verify at the point of collection (sign-up, newsletter, contact, and order forms)
\n
Any other client-side verification or cases involving one piece of data at a time
\n

\n","_postman_id":"0cb13e0a-4725-40ff-bdcd-b9eda46e0dc6"},{"name":"Server-side API Key","item":[{"name":"Email, Phone, and Address","id":"60703038-1cbc-4161-a5fb-cc7da76c9026","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: {{api_key}}"}],"body":{"mode":"raw","raw":"{\n \"email\": \"sales@validity.com\",\n \"phone\": \"18009618205\",\n \"address\": {\n \t\"address1\": \"4010 Boy Scout Boulevard, Suite 1100\",\n \t\"city\": \"Tampa\",\n \t\"state\": \"FL\",\n \t\"zip\": \"33607\"\n }\n}"},"url":"{{rt_base_url}}/api/v4/fullverify","description":"

You must provide at least one of the following fields in your request: email, phone, or address.

You can include just one, two, or all three, depending on your use case.

Phone number and mailing address verification available for the United States and Canada only at this time.

\n","urlObject":{"path":["api","v4","fullverify"],"host":["{{rt_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"7eac7e7c-0d88-4687-872e-1542751bece3","name":"Valid Email, Valid Phone, and Valid Address","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: api-key-here"}],"body":{"mode":"raw","raw":"{\n \"email\": \"sales@validity.com\",\n \"phone\": \"18009618205\",\n \"address\": {\n \t\"address1\": \"4010 Boy Scout Boulevard, Suite 1100\",\n \t\"city\": \"Tampa\",\n \t\"state\": \"FL\",\n \t\"zip\": \"33607\"\n }\n}"},"url":"https://bpi.briteverify.com/api/v4/fullverify"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Thu, 14 May 2020 20:00:27 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"ETag","value":"W/\"4ff16a9e3e06a519c6ece4811dad5f18\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"X-Request-Id","value":"994beec2-0cc4-40cb-afff-910ae8010ec2"},{"key":"X-Runtime","value":"2.399402"}],"cookie":[],"responseTime":null,"body":"{\n \"email\": {\n \"address\": \"sales@validity.com\",\n \"account\": \"sales\",\n \"domain\": \"validity.com\",\n \"status\": \"valid\",\n \"status_detail\": null,\n \"enrichment\": []\n },\n \"phone\": {\n \"number\": \"18009618205\",\n \"service_type\": \"land\",\n \"phone_location\": null,\n \"status\": \"valid\",\n \"errors\": []\n },\n \"address\": {\n \"address1\": \"4010 W Boy Scout Blvd Ste 1100\",\n \"address2\": \" \",\n \"city\": \"Tampa\",\n \"state\": \"FL\",\n \"zip\": \"33607-5796\",\n \"status\": \"valid\",\n \"errors\": [],\n \"corrected\": true\n },\n \"duration\": 0.392828819\n}"}],"_postman_id":"60703038-1cbc-4161-a5fb-cc7da76c9026"}],"id":"5fed52bf-d882-4703-ad57-3e93e68f1ffa","description":"

This endpoints assumes use of Server-side API Keys.

Examples of Server-side use cases:

Periodic cleansing of your customer database
\n
Pre-flight verification on a mailing list
\n
Any other server-side verification or cases involving sets of data
\n

\n","_postman_id":"5fed52bf-d882-4703-ad57-3e93e68f1ffa"}],"id":"cb129a5a-74c4-41d8-81a7-b212031d0eaa","description":"

Real-Time Single Transaction API is a JSON-based REST Web Service.

Supported Verifications Types

Email Addresses
Phone numbers (U.S. and Canadian)
Mailing Addresses (U.S. and Canadian)

This API should be used for on demand interactive validation when a user enters them in a web form or mobile application.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Secure Use
All client-side implementations are required to use public keys with domain validation.
Important: Neglecting to use Public Keys exposes integrating applications to unnecessary risks that may result in loss of verification credits, which are not refundable. Validity does not take responsibility for API key abuse that could have been prevented by using security features like Public Keys on a client-side implementation.

Use cases for each API Key type:

\n\n\n\n\n\n\n\n\n\n\n\n\n

Server-side	Client-side
Periodic cleansing of your customer database. Pre-flight verification of a mailing list. Any other server-side verification or cases involving sets of data.	Verify at the point of collection (sign-up, newsletter, contact, and order forms). Any other client-side verification or cases involving one piece of data at a time.

Performance & Rate Limiting

Real-time API is intended for validating emails, phone numbers, and mailing addresses one-by-one. Use Bulk API↗ for all other scenarios.

Response Statuses

To learn more about statuses returned, see Response Statuses & Errors ↗

\n","_postman_id":"cb129a5a-74c4-41d8-81a7-b212031d0eaa"},{"name":"Bulk Verification","item":[{"name":"Account Information","item":[{"name":"Credits","id":"07beceb3-2961-4d5b-93a4-9cfeb30f42fa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"disabled":false,"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"ApiKey: {{api_key}}"}],"body":{"mode":"raw","raw":""},"url":"{{bulk_base_url}}/api/v4/accounts/credits","description":"

This endpoint will return your account credit balance and credits in reserve*, current as of the recorded_on timestamp.

*Credits in reserve are those being held for currently processing list uploads (via manual upload or bulk api upload)

\n","urlObject":{"path":["api","v4","accounts","credits"],"host":["{{bulk_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"d32b05bf-5d52-4ce9-a658-6c63176767da","name":"Credit Balance","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: api-key-here"}],"url":"https://bulk-api.briteverify.com/api/v4/accounts/credits"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"credits\": 2165,\n \"credits_in_reserve\": 500,\n \"recorded_on\": \"2021-07-27T21:10:10.000+0000\"\n}"}],"_postman_id":"07beceb3-2961-4d5b-93a4-9cfeb30f42fa"}],"id":"f3a4f0cd-7d6d-4487-94dc-7bd9d70deb93","_postman_id":"f3a4f0cd-7d6d-4487-94dc-7bd9d70deb93","description":""},{"name":"Lists","item":[{"name":"Create List","id":"38b4c9eb-31b1-4b8e-9295-a783d8043bc1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","type":"text","value":"ApiKey: {{api_key}}"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"directive\": \"start\",\n \"contacts\": [\n { \n \"phone\": \"4444444444\",\n \"email\": \"hello@example.com\"\n },\n { \n \"phone\": \"5555555555\",\n \"email\": \"goodbye@example.com\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{{bulk_base_url}}/api/v4/lists","description":"

Create a Validation List

POST /api/v4/lists

Description

This endpoint creates a new, empty list into which you can insert contacts objects.

A contact can contain:
\n
- Up to one email
  \n
- Up to one phone number
  \n
- Up to one mailing address
  \n
\n
The list will not start processing until you pass the directive start.
\n
If no directive is passed, the list remains in an open state to allow adding more contacts later.
\n

URL Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description
`list_id`	String	❌	If adding to an existing open list. Leave blank to create a new list.

Request Body

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`directive`	String	❌	Values: `start` or `terminate`. Controls the list status. See more in Working with Open Lists.
`contacts`	Array	✔️	Array of contact objects. Each object can have one email, phone, and address. Max 100,000 per request.

Contact Object Fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`email`	String	❌	Email address of the contact.
`phone`	String	❌	Phone number of the contact.
`address`	Object	❌	Mailing address of the contact.

Address Object Fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`address1`	String	❌	Address line 1.
`address2`	String	❌	Address line 2.
`city`	String	❌	City.
`state`	String	❌	State (e.g., \"MA\").
`zip`	String	❌	ZIP or postal code.

Working with Open Lists

When you create a list without passing \"directive\": \"start\", the list remains in an open state.

An open list allows you to:

Add more contacts later using POST /api/v4/lists/:list_id.
\n
Start processing the list at any time by passing \"directive\": \"start\" to the same endpoint with the list_id.
\n
Terminate (cancel) the list by passing \"directive\": \"terminate\".
\n

\n
⚠️ Important:
Use the list_id returned in the response to manage the list’s lifecycle.
\n

Notes

The list will remain in an open state unless you pass \"directive\": \"start\" in the request.
\n
results_path is only available once the list is completed (state = complete).
\n

\n","urlObject":{"path":["api","v4","lists"],"host":["{{bulk_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"613c0bf1-14d4-4563-a253-a4bc6b79b246","name":"Create list","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"ApiKey: api-key-here"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"contacts\": [\n { \n \"email\": \"hello@example.com\",\n \"phone\": \"4444444444\",\n \"address\": {\n \"address1\": \"200 Clarendon St\",\n \"address2\": \"Unit 2200\",\n \"city\": \"Boston\",\n \"state\": \"MA\",\n \"zip\": \"02115\"\n }\n \n },\n { \n \"email\": \"hello@example.com\",\n \"phone\": \"4444444444\",\n \"address\": {\n \"address1\": \"200 Clarendon St\",\n \"address2\": \"Unit 2200\",\n \"city\": \"Boston\",\n \"state\": \"MA\",\n \"zip\": \"02115\"\n }\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://bulk-api.briteverify.com/api/v4/lists"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 27 May 2020 01:45:35 GMT"},{"key":"Connection","value":"close"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"ETag","value":"W/\"8f65a70267ae90b50b94fc0751b49921\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"Set-Cookie","value":"_bvapp_session=b09OZTQrRElBcVJSMkxjVEJYaFhhamtBWUh1UzVtUGFzL0R3akYreUNPQlBJYjFMN0VlNjJDSGRQbUhvVU9wc3NaWkIyTzZUdzN2R1M0YUQ0RUtkYW92WVhXajBtOVlBY3RCM2dMck1mbzhsbWs1bllyNEpxeUx2VWFtRVB1NXhVVEdNOFExeDJjY0RsUjZ3enphTElnPT0tLWl0c3RSaFlZUTZjeS9Pa2JuOUZDSFE9PQ%3D%3D--8cfd3c8a47a613f10767f49a745ed5e5af9bae53; path=/; HttpOnly; SameSite=Lax"},{"key":"X-Request-Id","value":"45fd9ef0-18eb-464b-9717-f1a94619b087"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"message\": \"created new list\",\n \"list\": {\n \"id\": \"list_id\",\n \"state\": \"open\",\n \"total_verified\": 0,\n \"total_verified_emails\": 0,\n \"total_verified_phones\": 0,\n \"page_count\": 0,\n \"progress\": 0,\n \"created_at\": \"08-10-2021 04:03 pm\",\n \"expiration_date\": null,\n \"results_path\": null\n }\n}"}],"_postman_id":"38b4c9eb-31b1-4b8e-9295-a783d8043bc1"},{"name":"Get Lists","id":"0b5a2a7a-4062-4327-ab0a-4675592e3cd6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"disabled":false,"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"ApiKey: {{api_key}}"}],"url":"{{bulk_base_url}}/api/v4/lists/","description":"

Retrieve Lists

GET /api/v4/lists

Description

This endpoint retrieves all lists created in the last 7 days if no date filter is provided.

You can filter the results using query parameters such as state, date, and page.

Filters can be combined to narrow down the results.
\n
If the results span multiple pages, the response will include a message field indicating the current page, e.g., \"Page 1 of 2\".
\n
Page size is 10
\n

Query Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`state`	String	❌	Filter lists by state.
`page`	Int	❌	Page number of the results. Default is 1.
`date`	String	❌	Filter lists created on a specific date (`YYYY-MM-DD`).

Available `state` values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

State	Description
open	The list is open and accepting additional uploads (pages).
verifying	The list is currently being verified.
complete	The verification process has finished successfully.
import_error	There was an error while importing one or more pages into the list.
loading	The list is currently being uploaded.
prepped	The list has been fully uploaded, prepped, and is ready for verification to start.
deleted	The list has been deleted and is no longer available.
terminated	The list was manually terminated or automatically closed after inactivity.

Example Requests

Get all lists from the last 7 days

GET /api/v4/lists

Filter by state

GET /api/v4/lists?state=complete

Filter by date

GET /api/v4/lists?date=2025-06-10

Combine filters (state + page)

GET /api/v4/lists?state=complete&page=2

Notes

The errors field is present only when the list has been terminated or encountered an import error.

\n","urlObject":{"path":["api","v4","lists",""],"host":["{{bulk_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"50fac934-8c0f-4967-ba07-127fdbbb1340","name":"Get lists","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: api-key-here"}],"url":"https://bulk-api.briteverify.com/api/v4/lists"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Page 1 of 2\",\n \"lists\": [\n {\n \"id\": \"list_id_1\",\n \"state\": \"open\",\n \"total_verified\": 0,\n \"total_verified_emails\": 0,\n \"total_verified_phones\": 0,\n \"page_count\": 0,\n \"progress\": 0,\n \"created_at\": \"08-10-2021 04:26 pm\",\n \"expiration_date\": null,\n \"results_path\": null\n },\n {\n \"id\": \"list_id_2\",\n \"state\": \"complete\",\n \"total_verified\": 2,\n \"total_verified_emails\": 1,\n \"total_verified_phones\": 1,\n \"page_count\": 1,\n \"progress\": 100,\n \"created_at\": \"08-10-2021 04:26 pm\",\n \"expiration_date\": \"08-17-2021 04:26 pm\",\n \"results_path\": \"{{base_host}}/api/v3/lists/list_id_2/export/1\"\n },\n {\n \"id\": \"list_id_3\",\n \"state\": \"terminated\",\n \"total_verified\": 0,\n \"total_verified_emails\": 0,\n \"total_verified_phones\": 0,\n \"page_count\": null,\n \"progress\": 0,\n \"created_at\": \"08-10-2021 04:03 pm\",\n \"expiration_date\": null,\n \"results_path\": null,\n \"errors\": [\n {\n \"code\": \"import_error\",\n \"message\": \"user terminated at 08-10-2021 04:07PM\"\n }\n ]\n }\n ]\n}"}],"_postman_id":"0b5a2a7a-4062-4327-ab0a-4675592e3cd6"},{"name":"List State","id":"b09c09dc-e11e-44a8-b53d-9f1fd9c6792d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"disabled":false,"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"ApiKey: {{api_key}}"}],"url":"{{bulk_base_url}}/api/v4/lists/","description":"

Retrieve a Specific List

GET /api/v4/lists/:list_id

Description

This endpoint fetches the details of a specific list using its list_id.

Use this endpoint to check the status and verifying progress of a list.
\n
Once the list has completed processing (state = complete), the results_path field will contain a URL to download the results, if it has expired or been terminated, the results_path will be null.
\n
If the list is expired or terminated, error details will be provided in the errors array.
\n

URL Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description
`list_id`	String	✔️	The unique ID of the list.

Notes

Use this endpoint to monitor the current status and progress of a list.
\n
If a list is terminated or expired, check the errors array for more details.
\n

\n","urlObject":{"path":["api","v4","lists",""],"host":["{{bulk_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"0dcba350-35b3-48dd-a29d-1c5d47e7e6cc","name":"List state → Complete","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: api-key-here"}],"url":"https://bulk-api.briteverify.com/api/v4/lists/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 07 Jul 2020 21:01:37 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"ETag","value":"W/\"84b65e2d5271408aefa4ece2605d775a\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"X-Request-Id","value":"34184299-bba9-4197-9dc4-69b86d50e5ea"},{"key":"X-Rack-Cache","value":"pass"},{"key":"Strict-Transport-Security","value":"max-age=2592000; includeSubDomains"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Content-Security-Policy","value":"default-src 'self' 'unsafe-inline' https:; connect-src wss: https:; font-src data: https:; img-src data: https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"list_id\",\n \"state\": \"complete\",\n \"total_verified\": 32,\n \"total_verified_emails\": 16,\n \"total_verified_phones\": 16,\n \"page_count\": 1,\n \"progress\": 100,\n \"created_at\": \"08-10-2021 05:06 pm\",\n \"expiration_date\": \"08-17-2021 05:07 pm\",\n \"results_path\": \"{{bulk_base_url}}/api/v3/lists/list_id/export/1\"\n}"}],"_postman_id":"b09c09dc-e11e-44a8-b53d-9f1fd9c6792d"},{"name":"List Results","id":"0a0cc29d-6d9f-4b0d-9aa5-4166775a8831","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"disabled":false,"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"ApiKey: {{api_key}}"}],"url":"{{bulk_base_url}}/api/v4/lists//export/","description":"

Get List Results

GET /api/v4/lists/:list_id/export/:page

Description

This endpoint retrieves the paged verification results for each contact in a list.

The export includes verification results for email, phone, and mailing address, depending on what was submitted in the contact.
\n
The export becomes available only after the list has finished processing (state = complete) and expires in 7 days from the time the list finishes processing.
\n
When a list is expired:
\n
- The list summary is still available with the /api/v4/lists/:list_id endpoint.
  \n
- Paged verification results are no longer available.
  \n
\n
Results are paginated. The response includes num_pages to indicate the total number of pages.
\n
The next_page field is not present. To retrieve subsequent pages, increment the page number manually.
\n
Page size is 100,000.
\n

URL Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description
`list_id`	String	✔️	The unique ID of the list.
`page`	Int	✔️	Page number of the export (starts at 1).

Example Requests

Standard user

GET https://bulk-api.briteverify.com/api/v4/lists/:list_id/export/1

Notes

The export is only available if the list has finished processing (state = complete).
If the list is still processing (verifying, pending, etc.), the export endpoint will return an error.
\n
Results are paginated. Use the num_pages value to determine how many pages are available.
There is no next_page field to get additional pages, increment the page number manually.
\n

\n","urlObject":{"path":["api","v4","lists","","export",""],"host":["{{bulk_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"9d8c4926-d58a-4729-ba0f-92afd016de1f","name":"Get list results (contacts parameter)","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: api-key-here"}],"url":"https://bulk-api.briteverify.com/api/v4/lists//export/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Thu, 28 May 2020 16:04:35 GMT"},{"key":"Connection","value":"close"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"ETag","value":"W/\"07681babff0a8cad00003c46c3563f4e\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"Set-Cookie","value":"_bvapp_session=R3BRMDJNdzl0WVBiY2dVRE1YbjEyTU9saUVOcGM4eElsb0V0MXJYbHJ4aktrM0k0eExrUTVFaFQvMTJkbkhPcm5VYUt5SkdEazlaZFloc0ZyUU56UDVOU2U1c3grM0ZXajZxdy91RkhIcmpJUFRDMTRubFRuN3VxcEJiS0VpUytwS0FXdU1TTDlLZG9UQTdYSE92N0VRPT0tLWhORFk4WU5nZzhJVHh1eU14YjBYOVE9PQ%3D%3D--0b83d22b8e5566b97eb6b91ee7afe57b37affceb; path=/; HttpOnly; SameSite=Lax"},{"key":"X-Request-Id","value":"7a5974ec-2bc1-423d-ba6d-3d3e00b0d222"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"num_pages\": 1,\n \"results\": [\n {\n \"email\": {\n \"email\": \"sales@validity.com\",\n \"status\": \"valid\",\n \"secondary_status\": \"role_address\"\n },\n \"phone\": {\n \"phone\": \"18009618205\",\n \"status\": \"valid\",\n \"secondary_status\": null,\n \"phone_service_type\": \"land\",\n \"phone_location\": null\n },\n \"address\": {\n \"address1\": \"200 Clarendon St Ste 2200\",\n \"address2\": null,\n \"city\": \"Boston\",\n \"state\": \"MA\",\n \"zip\": \"02116-5051\",\n \"status\": \"valid\",\n \"secondary_status\": null,\n \"corrected\": \"true\"\n }\n },\n {\n \"email\": {\n \"email\": \"goodbye@example.com\",\n \"status\": \"invalid\",\n \"secondary_status\": \"email_domain_invalid\"\n },\n \"phone\": {\n \"phone\": \"5555555555\",\n \"status\": \"invalid\",\n \"secondary_status\": \"invalid_phone_number\",\n \"phone_service_type\": null,\n \"phone_location\": null\n }\n }\n ]\n}"},{"id":"d1400123-f062-4983-b708-6b29a64a176e","name":"Get list results (emails parameter)","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: {{api_key}}"}],"url":"{{bulk_base_url}}/api/v4/lists//export/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Thu, 28 May 2020 16:04:35 GMT"},{"key":"Connection","value":"close"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"ETag","value":"W/\"07681babff0a8cad00003c46c3563f4e\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"Set-Cookie","value":"_bvapp_session=R3BRMDJNdzl0WVBiY2dVRE1YbjEyTU9saUVOcGM4eElsb0V0MXJYbHJ4aktrM0k0eExrUTVFaFQvMTJkbkhPcm5VYUt5SkdEazlaZFloc0ZyUU56UDVOU2U1c3grM0ZXajZxdy91RkhIcmpJUFRDMTRubFRuN3VxcEJiS0VpUytwS0FXdU1TTDlLZG9UQTdYSE92N0VRPT0tLWhORFk4WU5nZzhJVHh1eU14YjBYOVE9PQ%3D%3D--0b83d22b8e5566b97eb6b91ee7afe57b37affceb; path=/; HttpOnly; SameSite=Lax"},{"key":"X-Request-Id","value":"7a5974ec-2bc1-423d-ba6d-3d3e00b0d222"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"status\":\"success\",\n \"num_pages\":\"2\",\n \"results\": [\n {\n \"email\": \"invalid@test.com\",\n \"status\": \"invalid\",\n \"secondary_status\": \"email_account_invalid\"\n },\n {\n \"email\": \"unknown@test.com\",\n \"status\": \"unknown\",\n \"secondary_status\": null\n },\n {\n \"email\": \"valid@test.com\",\n \"status\": \"valid\",\n \"secondary_status\": \"role_address\"\n },\n {\n \"email\": \"accept_all@test.com\",\n \"status\": \"accept_all\",\n \"secondary_status\": \"role_address\"\n }\n ]\n}"}],"_postman_id":"0a0cc29d-6d9f-4b0d-9aa5-4166775a8831"},{"name":"List Delete","id":"6c9b9c05-a4a0-435e-a064-af7d9476719d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"disabled":false,"key":"Content-Type","value":"application/json"},{"key":"Authorization","type":"text","value":"ApiKey: {{apikey}}"}],"url":"{{bulk_base_url}}/api/v4/lists/","description":"

Delete a List

DELETE /api/v4/lists/:list_id

Description

This endpoint deletes a specific list.

Once the deletion is completed, the list will no longer exist.
\n
⚠️ This action cannot be reversed.
\n
The list must be in one of the following states to be deleted:
\n
- complete
  \n
- delivered
  \n
- prepped
  \n
- import_error
  \n
\n

Attempting to delete a list in any other state (such as verifying or pending) will result in an error (add the result error message).

URL Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Required	Description
`list_id`	String	✔️	The unique ID of the list to be deleted.

","urlObject":{"path":["api","v4","lists",""],"host":["{{bulk_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"f7829cdb-dfee-4da9-820f-c1fd718749b3","name":"List State → Complete","originalRequest":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"ApiKey: api-key-here"}],"url":"https://bulk-api.briteverify.com/api/v4/lists/"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Thu, 21 Jul 2022 18:16:05 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"ETag","value":"W/\"2b5aaec7ba71463e4da15a2d13cec4b9\""},{"key":"Cache-Control","value":"max-age=0, private, must-revalidate"},{"key":"X-Request-Id","value":"29083613-164c-412f-8242-539abb64d91e"},{"key":"X-Rack-Cache","value":"pass"},{"key":"Strict-Transport-Security","value":"max-age=15552000; includeSubDomains"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-XSS-Protection","value":"1; mode=block"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"Referrer-Policy","value":"strict-origin-when-cross-origin"},{"key":"Content-Security-Policy","value":"default-src 'self' 'unsafe-inline' https:; connect-src wss: https:; font-src data: https:; img-src data: https:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"list\": {\n \"id\": \"list_id\",\n \"state\": \"deleted\",\n \"total_verified\": 32,\n \"total_verified_emails\": 16,\n \"total_verified_phones\": 16,\n \"page_count\": 1,\n \"progress\": 100,\n \"created_at\": \"07-18-2022 12:42 pm\",\n \"expiration_date\": null,\n \"results_path\": null\n }\n}"}],"_postman_id":"6c9b9c05-a4a0-435e-a064-af7d9476719d"}],"id":"944cd18b-8cad-43c2-9e47-7b1e91ba5935","_postman_id":"944cd18b-8cad-43c2-9e47-7b1e91ba5935","description":""}],"id":"e673d752-0030-466c-9e7e-4f2fed63c848","description":"

Bulk Verification API is a RESTful web service that supports email and phone address verifications at speed and scale.

Supported Verifications Types

Email Addresses
\n
Phone numbers (U.S. and Canadian)
\n
Mailing Addresses (U.S. and Canadian)
\n

Full Contact Verification
Each object in contacts array can have any subset of email/phone/address properties for verification. For example, object can contain just the email property with email address for verification.

Paging
For lists larger than 100,000 contacts , use paging to upload the list in chunks (see Add Contacts below).
Note: When adding pages to an open list, API responses don't contain a running total of items in the list. The total count of verifications becomes available at the completion of full list verification process.

The page size for exporting results is also 100,000.

After the initial list creation, that list remains open to allow for addition of items. Open lists are automatically terminated after 15 minutes of inactivity.

HTTP Response Status Codes and Error Messages

The table below provides details on the HTTP status codes and JSON status messages that the Bulk Verification API can return. These responses help indicate whether a request was successful or if it failed due to invalid input, incorrect request structure, or other issues.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP Code	JSON Status	Message
200	success	-
400	param_error	Date is in incorrect format
400	invalid_state	The provided list is in an invalid state -- state is {status} and needs to be {required_status} to continue.
400	invalid_state	Directive must be one of 'terminate' or 'start'
400	missing_data	Cannot terminate a list without a valid list id
400	missing_data	Request has missing or invalid emails array
400	missing_data	Request has missing or invalid contacts array
400	missing_data	Request has missing or invalid emails or contacts array
400	duplicate_data	Request has both emails and contacts params
400	exceeds_limit	Request exceeds the limit of {num} entries in a single request
400	invalid_page_number	Page number {page_num} is invalid.
400	page_not_found	Page not found for page number {page_num}.
404	not_found	No list found
404	not_found	No matching list found
404	not_found	Route not found.
422	import_error	There was an error processing the list
422	update_error	Error trying to save the apply status
422	list_expired	Download unavailable. List with id {list_id} has expired.
422	list_uploads_incomplete	Not ready to start. Input page uploads have not completed.

Standard Workflow

Create a List:
POST /api/v4/lists
\n
Add Contacts:
POST /api/v4/lists/:list_id
\n
Terminate a List (if needed):
POST /api/v4/lists/:list_id
with body: { \"directive\": \"terminate\" }
\n
Start Processing:
POST /api/v4/lists/:list_id
with body: { \"directive\": \"start\" }
\n
Get List State:
GET /api/v4/lists/:list_id
\n
Get List Results
GET /api/v4/lists/:list_id/export/:page
\n

\n","_postman_id":"e673d752-0030-466c-9e7e-4f2fed63c848"}]}

Authorization

API Key Best Practices

Rate Limits and Performance

HTTP Response Codes

Email Responses

Status Field

Status Detail

Enrichment Attribute

Optional Attributes

Phone Responses

Status and Errors Fields

Addresses Responses

Status and Errors Fields

Examples of Client-side use cases:

Examples of Server-side use cases:

Create a Validation List

Description

URL Parameters

Request Body

Contact Object Fields

Address Object Fields

Working with Open Lists

Notes

Retrieve Lists

Description

Query Parameters

Available state values

Example Requests

Get all lists from the last 7 days

Filter by state

Filter by date

Combine filters (state + page)

Notes

Retrieve a Specific List

Description

URL Parameters

Notes

Get List Results

Description

URL Parameters

Example Requests

Standard user

Notes

Delete a List

Description

URL Parameters

HTTP Response Status Codes and Error Messages

Standard Workflow

Available `state` values