{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"84e52e3e-e6e9-4a84-9fa6-84b8ae4e9692","name":"BriteVerify API Documentation","description":"## Authorization\n\nAPI key is required to access BriteVerify API:\n\n1. Log into your account and navigate to the [API Keys](https://app.briteverify.com/account/api_keys) tab.\n2. 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.\n3. Select a key type - select _Client-side_ type for keys used in a client-side(browser) implementation, otherwise select _Server-side_. See [Public Keys ↗](https://knowledge.validity.com/s/articles/Public-Keys-for-the-Real-time-Single-Transaction-API?language=en_US) for more information about client side initiated real time validations.\n4. Once a key is created, it is immediately available for use and should appear in the list.\n    \n\n---\n\n## API Key Best Practices\n\nAPI 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**.\n\nWhen a key is compromised or when there is a suspicion of a key being abused, that key must be immediately deactivated and replaced:\n\n1. Navigate to the [API Keys](https://app.briteverify.com/account/api_keys) tab in your BriteVerify account.\n2. Locate the key in question and click on the Actions gear, then click 'Deactivate'. **This action cannot be undone.**\n3. Generate a new key and replace the old one in your code.\n    \n\n---\n\n## Rate Limits and Performance\n\n| **Endpoint** | **Rate Limits** | **Processing Speeds** | **Notes** |\n| --- | --- | --- | --- |\n| Real-time Single Transaction API | **500**  <br>verifications per key, per minute. Applies to both server-side and client-side (public) keys.  <br>  <br>**25**  <br>verifications per client IP address, per minute. Applies to client-side (public) keys only.  <br>  <br>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.  <br>If you believe your transactional traffic will be greater than 500 requests per key, per minute, contact [Validity Support](https://knowledge.validity.com/s/contactsupport) team for additional guidance. |\n| Bulk API | **100K**  <br>Emails per page  <br>  <br>**1M**  <br>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. |\n\n## HTTP Response Codes\n\n- **200** Success\n- **400** Bad Request (indicates invalid or missing query and/or body parameters)\n- **401** Unauthorized (no valid API key provided)\n- **403** Forbidden (indicates lack of access to the performed operation)\n- **404** Not Found (indicates invalid parameters or missing API endpoint)\n- **422** Unprocessable Entity (indicates invalid data or a request that violates business rules)\n- **429** Too Many Requests (Rate limit have been exceeded, retry after some time)\n- **500** Internal Server Error (An unexpected error on Validity BriteVerify side)\n    \n\n---\n\n## Email Responses\n\n### Status Field\n\nThe **status** field will return one of the following:\n\n| **Status** | **Explanation** | **Suggested Action** |\n| --- | --- | --- |\n| `valid` | The email address is a valid account. | **Safe to mail** |\n| `invalid` | The email address is invalid. See Secondary Statuses section below for more details. | **Do not mail** |\n| `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**.  <br>  <br>These emails might still accept messages, but they are more likely to bounce or underperform. If you decide to mail them, consider:  <br>  <br>– Monitor bounce rates closely.  <br>– Send gradually to reduce deliverability risk.  <br>– Avoid mailing if your ESP’s bounce tolerance is low (e.g., ≤5%).  <br>– Regularly revalidate these addresses before future sends. |\n\n### Status Detail\n\nFor 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:\n\nPossible values for non-valid emails:\n\n| **status_detail** | **Explanation** |\n| --- | --- |\n| email_address_invalid | Email address format is incorrect. For example, james0uwerwe#com is not in the correct email format of [inbox@domain.com](https://mailto:inbox@domain.com). Many of these can be prevented by applying simple regular expression to data prior to verification. |\n| 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](https://mailto:inbox@briteeeeverify.com) is an invalid email since it pertains to a domain that does not exist. |\n| email_account_invalid | The email account (the inbox) does not exist at the given domain. For example, [not-an-inbox@briteverify.com](https://mailto:not-an-inbox@briteverify.com) results in a secondary status of email_account_invalid. |\n| 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. |\n| 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. |\n| temporary_error | This email is Unknown status because the email provider indicated a temporary error. Try to validate these email addresses again later. |\n| 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. |\n| 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. |\n\n### Enrichment Attribute\n\nThis field provides additional context about the verified email address, indicating specific characteristics or detected conditions.\n\nMultiple enrichment values may be returned for the same email (e.g., `[\"typo\", \"corrected\"]`).\n\n| Enrichment | **Explanation** |\n| --- | --- |\n| duplicated | The email address has already appeared earlier in the same verification request. |\n| typo | A typo was detected in the email address. |\n| corrected | The email address was automatically corrected |\n| disposable | The domain belongs to a disposable email provider. |\n| role address | The email represents a role-based or generic account (e.g., `info@`, `support@`, `sales@`). |\n| alias | The address appears to be an alias or forwarding address (e.g., Gmail “plus addressing” like `user+promo@gmail.com`). |\n| freemail | The domain belongs to a free, public email provider (e.g., Gmail, Yahoo, Outlook). |\n| education | The domain is associated with an educational institution. |\n| government | The domain is associated with a government entity. |\n| military | The domain is associated with a military organization. |\n\n### Optional Attributes\n\nIf **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.\n\nThese fields provide details about the automatically corrected version of the email address and its verification results.\n\n| **Attribute** | **Explanation** |\n| --- | --- |\n| 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](https://mailto:user@gmial.com) → [user@gmail.com](https://mailto:user@gmail.com)). |\n| corrected_email_status | The verification status of the corrected email. This field follows the same possible values listed in the Status table above. |\n| 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. |\n\n## Phone Responses\n\n### Status and Errors Fields\n\nThe **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| **Status** | **Error Code** | Explanation |\n| --- | --- | --- |\n| valid | \\- | \\- |\n| invalid | invalid_phone_number | The provided number does not exist. |\n| invalid | blank_phone_number | The phone number field is blank. This could be due to improper formatting. |\n| invalid | invalid_format | The number provided has insufficient or inaccurate information. |\n| invalid | invalid_prefix | Unable to verify the phone prefix or first 7 digits. |\n| unknown | \\- | \\- |\n\n## Addresses Responses\n\n### Status and Errors Fields\n\nThe **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| **Status** | **Error Code** | Explanation |\n| --- | --- | --- |\n| valid | \\- | \\- |\n| invalid | suite_invalid_missing | While the street address is valid, the suite/apartment is missing or invalid. |\n| invalid | multiple_match | Two or more possible addresses are matched and so unable to choose one over the other. |\n| invalid | missing_minimum_inputs | Missing minimum inputs to verify address. |\n| invalid | zip_code_invalid | The address could not be verified based on the postal code provided. |\n| invalid | unknown_street | Could not conclusively locate the input street to its unique street name. |\n| invalid | directionals_invalid | Directional information did not match with the suffix provided (Ave, St, Blvd) |\n| invalid | non_deliverable_address | Address cannot be delivered to. |\n| invalid | suite_invalid | While the street address is valid, the suite/apartment provided is invalid. |\n| invalid | suite_missing | While the street address is valid, the suite/apartment provided is required. |\n| invalid | street_number_invalid | The building or house number is invalid. |\n| invalid | street_number_missing | The building or house number is required. |\n| invalid | box_number_invalid | The PO box number is invalid. |\n| invalid | box_number_missing | The PO box number is required. |\n| invalid | pmb_required | The Private mailbox number is missing. |\n| unknown | \\- | \\- |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"11411276","collectionId":"84e52e3e-e6e9-4a84-9fa6-84b8ae4e9692","publishedId":"SzmjyuQH","public":true,"publicUrl":"https://docs.briteverify.com","privateUrl":"https://go.postman.co/documentation/11411276-84e52e3e-e6e9-4a84-9fa6-84b8ae4e9692","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"37ACF0"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2020-08-20T16:16:56.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Production","id":"cac17b65-f22d-463a-9a66-9e3dee4b37c8","owner":"11411276","values":[{"key":"rt_base_url","value":"https://bpi.briteverify.com","enabled":true},{"key":"bulk_base_url","value":"https://bulk-api.briteverify.com","enabled":true},{"key":"api_key","value":"api-key-here","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://briteverify.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Production","value":"11411276-cac17b65-f22d-463a-9a66-9e3dee4b37c8"}],"canonicalUrl":"https://docs.briteverify.com/view/metadata/SzmjyuQH"}