Core concepts

Not a developer?

Verifalia makes email verification and mailing list cleaning easy: just upload your list, and you'll get a detailed report. Learn more

Using the Verifalia API

Authentication

Data interchange format

The data interchange format for the Verifalia API is JSON encoded as UTF-8, where the body of every POST and PUT requests made against the API should have a MIME Content-Type header set to application/json, with the exception of the job submission through file import which allows for a broader range of values.

Similarly, the default format for the API response body is still a JSON object, encoded as UTF-8, with its Content-Type HTTP header equals to application/json as well.

Certain APIs can also output data in alternative formats: to request on of these formats instead of JSON, the API consumer must specify the related media type by way of the Accept HTTP header.

API endpoints (base URLs)

Verifalia provides distinct endpoints for API consumption, with identical features and behavior, which are used to increase the service availability and speed. These endpoints, which are the base for all the URLs referenced in this documentation, are:

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

API consumers which authenticate using the TLS mutual authentication method, must instead use the following API endpoints:

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

Most Verifalia official SDKs already implement an automatic retry, fail-safe logic, so you don't have to worry about picking one API endpoint or the other. If you are developing a custom API SDK, however, it is recommended that for each API request, the client picks a random endpoint and, in the event of failure, uses the next one and retries the original request.

Single base URL

While we recommend applying an automatic retry logic to the distinct endpoints mentioned above - which allows to be backed by our premium uptime SLA -, we also support a single API DNS record api.verifalia.com which points to the aforementioned API hosts, in a round-robin fashion.

Thus, simpler client implementations which can't afford implementing a full auto-retry logic (cURL, for example) may point to this single base URL instead:

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

Similarly, API consumers which authenticate using the TLS mutual authentication method and can't apply an automatic retry logic to the distinct endpoints mentioned above, may point to this single base URL:

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

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.

Request a compressed response
Language:

curl -u username:password \
    --compressed \      
    https://api.verifalia.com/v2.6/email-validations

// No code needed, the SDK handles compression automatically

// No code needed, the SDK handles compression automatically

// No code needed, the SDK handles compression automatically

// No code needed, the SDK handles compression automatically

// No code needed, the SDK handles compression automatically

# No code needed, the SDK handles compression automatically

API limits

To help prevent strain on Verifalia's servers, our API imposes a rate limit on API invocations: a single IP address can't issue more than 6 HTTPS requests per second to our API endpoints, with a burst limit of 15 HTTPS requests per second: this does not limit the number of concurrent running email verification jobs a single IP address or account may have however, which is unlimited. If a request exceeds the limit, we return an HTTP 429 status code.

To avoid hitting the rate limit, it is suggested to reduce the number of requests against our API endpoints: for example, instead of using a loop or a script to verify individual email addresses retrieved from a database, it is advisable to submit a single email verification job with all the email addresses to verify. Not only this would require far less HTTPS requests, it would also be faster and allow to mark duplicates on the submitted entries.

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).

Key	Description
`cursor`	A `string` with the `meta.cursor` value obtained from a previous API call: Verifalia replies with the next page of results.
`cursor:prev`	A `string` with the `meta.cursor` value obtained from a previous API call: Verifalia replies with the previous page of results.

All paginated results share the base JSON structure shown hereafter.

JSON structure

Property	Description
`meta?.isTruncated?`	An optional `boolean` which signals whether the response is truncated or not. If not present, the response is not truncated.
`meta?.cursor?`	An optional `string` with an opaque token that must be used to retrieve the next (and previous, where available) result page.
`data`	An array with zero or more items for the current page of results; the structure of the actual items varies and depends on the type of requested data.

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:

HTTP status code	Meaning
`200`	Success. The API request completed without any error.
`202`	Accepted. The API request has been queued and will be completed as soon as possible by the system.
`303`	See other. The `Location` HTTP header contains the final URI of the requested resource.
`400`	Bad request. Perhaps you are not sending a required parameter or not passing the information using JSON.
`401`	Unauthorized request. No valid username or password (that is, the credentials of the user) provided; please see how to authenticate to the Verifalia API for additional details.
`402`	Payment required. Either the credit of your account is too low to process the validation request or the request would exceed the maximum number of monthly processable items.
`403`	Forbidden request: the client has not enough permissions to perform an action on a resource.
`404`	Not found. The requested resource does not exist on the server.
`406`	Not acceptable. The requested resource is not available with respect to its current state.
`410`	Gone. The requested resource has been deleted and is no longer available on the server.
`415`	v2.2+ Unsupported media type. The specified content type (or charset) is not supported or is invalid according to the provided data.
`429`	Too many requests. Returned when a request cannot be served due to the application's rate limit having been exhausted for the client.
`5xx`	Server error. Verifalia failed to fulfill an apparently valid request.

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:

type

A URI that pinpoints the exact type of error.

title

A short, human-readable description summary of the problem.

status

The original HTTP status code generated by the origin server for this occurrence of the problem.

detail

A thorough, easy-to-understand explanation of the issue; it may contain precise details about the error and its potential causes.

Problem detail JSON sample

{
    "type": "/problems/forbidden",
    "title": "Access denied",
    "status": 403,
    "detail": "The user or browser app is not allowed to access this resource, as permission
        has been denied by the account administrator. Please note that once saved, permissions
        and settings may take up to 10 minutes for changes to take effect."
}

Using the Verifalia API

Authentication

On this page:

Core concepts

Data interchange format

API endpoints (base URLs)

Single base URL

Endpoints security

Content compression

API limits

Cross-Origin Resource Sharing

Paginated results

HTTP status codes

Problem details

Need Help?

We're here to assist you.

Visit Our Help Center

Explore our collection of technical and non-technical articles about Verifalia's services.

Help center

Send Us a Message

Reach out to us with any questions or comments. Support is always free of charge.

Send a message

Want to chat?

Click the button below to chat live with one of our support team right now.

Online chat

Core concepts

Not a developer?

Data interchange format

API endpoints (base URLs)

Single base URL

Endpoints security

Content compression

Request a compressed response
Language:

API limits

Cross-Origin Resource Sharing

Paginated results

Paginated response structure example

HTTP status codes

Problem details v2.6+

Problem detail JSON sample

Need Help?

We're here to assist you.

Visit Our Help Center

Send Us a Message

Want to chat?

Latest tweets - twitter.com/verifalia

From our blog

Core concepts

Not a developer?

Data interchange format

API endpoints (base URLs)

Single base URL

Endpoints security

Content compression

Request a compressed response Language: cURL .NET (C#) Go Java Javascript PHP Ruby

API limits

Cross-Origin Resource Sharing

Paginated results

Paginated response structure example

HTTP status codes

Problem details v2.6+

Problem detail JSON sample

Need Help?

We're here to assist you.

Visit Our Help Center

Send Us a Message

Want to chat?

Latest tweets - twitter.com/verifalia

From our blog

Request a compressed response
Language: