Core concepts

API endpoints (base URLs)

Verifalia offers multiple API endpoints with the same features and behavior to improve service availability and performance. These endpoints serve as the base URLs for all requests referenced in this documentation:

• https://api-1.verifalia.com/v2.7
• https://api-2.verifalia.com/v2.7
• https://api-3.verifalia.com/v2.7

For API consumers using TLS mutual authentication, the following endpoints must be used instead:

• https://api-cca-1.verifalia.com/v2.7
• https://api-cca-2.verifalia.com/v2.7
• https://api-cca-3.verifalia.com/v2.7

Most official Verifalia SDKs include built-in logic for automatic retries and failover, so you typically don’t need to worry about choosing a specific endpoint. However, if you're developing a custom API client, it's recommended that each API request randomly selects an endpoint. If the request fails, the client should automatically retry using the next available endpoint.

Single base URL

While we recommend using automatic retry logic with the individual API endpoints listed above - allowing clients to benefit from our premium uptime SLA - we also provide a single API DNS record, api.verifalia.com, which distributes requests across those endpoints using round-robin DNS.

This is useful for simpler client implementations (such as cURL) that don't support full retry logic; these clients can instead use the following single base URL:

https://api.verifalia.com/v2.7

Similarly, for API consumers using TLS mutual authentication who cannot implement automatic retries, we offer the following single base URL:

https://api-cca.verifalia.com/v2.7

Endpoints security

The Verifalia REST API is served over HTTPS only: to ensure data privacy, unencrypted HTTP is not supported. Also, our HTTPS endpoints require your web client to support Server Name Indication (SNI), a standard widespread extension to the TLS protocol which may be missing in some obsolete systems (most notably, in Microsoft Windows XP and lower version operating systems as well as in wget prior to version 1.14).

For additional safety, our endpoints support these TLS protocol versions:

• TLS 1.0 Deprecated
• TLS 1.1 Deprecated
• TLS 1.2
• TLS 1.3

Content compression

Verifalia can generate gzip compressed responses for any API request; for this, the API consumer must advertise it supports the gzip compression scheme, by way of the Accept-Encoding HTTP header. In all cases, we may choose to serve the response uncompressed in the event its length is too small to gain a relevant advantage or for other internal reasons: API consumers should always check the Content-Encoding HTTP header to determine whether the response is compressed or not.

API limits

To help reduce server load and ensure fair usage, the Verifalia API enforces a rate limit on incoming requests: specifically, a single IP address may send up to 18 requests per second, with a burst limit of 45 requests per second, across all API endpoints combined. This limit does not affect the number of concurrent email verification jobs an IP address or account can run - there is no limit on that!

If a request exceeds the allowed rate, the API responds with an HTTP status code of 429 (Too Many Requests).

Cross-Origin Resource Sharing

The Verifalia API supports CORS, so that you may send requests directly from the browser, however remember to never expose your account credentials or the credentials of one of your users. If a credentials pair become compromised, you will want to roll a new one.

As a safer alternative, you may want to configure and use a browser app through the Verifalia client area, together with one or more throttling and/or firewall rules.

Paginated results

Many Verifalia operations return paginated results whenever the response output is large or for other technical reasons; in these cases, the API returns a flag which signals whether the response is truncated and a cursor token which must be used to retrieve the next (or previous, where available) page of results. Each page eventually includes an updated cursor token which allows to get the next result page with a subsequent API call.

To iterate over a set of result pages, API consumers must invoke the target API passing one of the following keys via query string, omitting any eventual filter and option (as the cursor token itself already refers to a filtered view of the items).

All paginated results share the base JSON structure shown hereafter.

Paginated results structure

meta object

Paginated response structure example

{
    "meta": {
        "isTruncated": true,
        "cursor": "tkxhHTv5xjrGLbtDAzY0IA=="
    },
    "data": [
        // ...
    ]
}

HTTP status codes

The Verifalia API uses conventional HTTP status codes to indicate success or failure of a request. Here are the possible HTTP status codes which the API may return:

Problem details v2.6+

In the event of client usage errors (4xx status codes) and server processing errors (5xx status codes), the API might send back a problem details JSON document. This document follows the guidelines in RFC 9457 and is sent with the MIME Content-Type application/problem+json, with the purpose of providing additional information about the failure in a format that both humans and machines can understand, going beyond just the HTTP response status code. API consumers need to be resilient and not assume that they'll always receive a problem details JSON document in response to failures, because the service might be unable to do that in certain error scenarios; additionally, the set of fields returned within problem detail JSON documents is extensible, and API consumers must be tolerant of any new, unrecognized fields they encounter and disregard them.

The structure of a problem details JSON document includes the following fields:

Permissions v2.7+

To access the Verifalia API, a user must be granted the appropriate permissions by an account administrator - or by another user who has the necessary user-management permissions. As a best practice, always request only the minimum set of permissions your app or user needs to function properly: requesting more permissions than necessary is considered a poor security practice and should be avoided.

Verifalia API permissions follow a straightforward naming convention in the format:

resource[:operation[:scope]]

where:

• resource refers to the entity being accessed, for example email-verifications;
• operation refers to the specific action, for example list;
• scope defines the scope of access, for example own.

If scope is not specified, the permission applies to the entire account. Similarly, if operation is omitted, the permission includes all operations for the specified resource.

Permissions list

account:read-defaults Read the default classification scheme and overrides, data retention and quality level for the account.

account:read-invoicing-details Read the invoicing details for the account, including tax ID.

account:write-defaults Update the default classification scheme and overrides, data retention and quality level for the account.

account:write-invoicing-details Update the invoicing details for the account, including tax ID.

credits:read-balance Read the number of credits in the account balance.

credits:read-consumption-history Read the historical consumption of credits.

email-verifications:delete Delete any completed email verification jobs of the account.

email-verifications:delete:own Delete completed email verification jobs submitted by the user.

email-verifications:list List any email verification jobs of the account, along with their basic information.

email-verifications:list:own List email verification jobs submitted by the user, along with their basic information.

email-verifications:read Read the details for any email verification jobs of the account, including the email addresses and their verification results.

email-verifications:read:own Read the details for the email verification jobs submitted by the user, including the email addresses and their verification results.

email-verifications:write-quality:own Set the quality level for the email verification jobs.

email-verifications:write-priority:own Set the priority for the email verification jobs, relative to the other users of the account.

email-verifications:write:own Submit new email verification jobs.

orders:list List orders of the account.

orders:read Read the details for the orders.

orders:write Place new orders and update the existing ones.

payment-methods:list List payment methods.

payment-methods:read Read payment methods details and settings.

payment-methods:write Add new payment methods and update existing payment method details and settings.

payment-methods:delete Delete payment methods.

quality-levels:list-custom List custom quality levels.

quality-levels:read-custom Read custom quality levels details.

support-tickets:write:own Create and send tickets to the customer support.

users:list List users and browser apps and retrieve their basic information.

users:read Read user and browser apps details and settings.

users:read:own Read own user details and settings.

users:delete Delete users and browser apps.

users:write Create new users and browser apps and update the existing ones.

users:write:own Update own user details and settings.

users:write-throttling Configure throttling rules for users and browser apps.

users:write-throttling:own Configure own throttling rules.

users:write-firewall Configure firewall settings for users and browser apps.

users:write-firewall:own Configure own firewall settings.

users:write-defaults Configure default settings for users and browser apps.

users:write-defaults:own Configure own default settings.

users:write-bot-detection Configure bot detection settings for users and browser apps.

users:write-bot-detection:own Configure own bot detection settings.

users:write-contact-methods Configure contact methods for users.

users:write-contact-methods:own Configure own contact methods.

users:write-trusted-origins Configure trusted origins.

users:write-trusted-origins:own Configure own trusted origins.

users:write-auth-methods Configure authentication methods and adjust their settings.

users:write-auth-methods:own Configure own authentication methods and adjust their settings.

users:write-permissions Configure permissions for users.