API call

Available endpoints

Name	URL	Description
Validate company data	/company/validate	Validation of various company parameters and their combinations.
Search company	/company/search	Company autocomplete.
Get company data	/company/get	Get more information about a company.
Validate e-mail	/email/validate	Validation of e-mail addresses and deliverability check.
Search e-mail	/email/search	E-mail autocomplete.
Validate location data	/location/validate	Validation of various location data and their combinations.
Search location	/location/search	Address autocomplete.
Get location data	/location/get	Get more information about a location.
Localization	/location/localize	Return list of addresses in given GPS location.
Validate name data	/name/validate	Validation of names and surnames.
Validate phone number	/phone/validate	Validation of phone numbers and their connection to the network.

Rate limiting

Requests to our API are rate limited. The rate limit is computed for a triple of IP address, project, and endpoint. The current rate limit is 5 000 requests per 900 seconds. You can use the response headers foxentry-rate-limit, foxentry-rate-limit-period and foxentry-rate-limit-remaining to check the currently applied limits.

Request structure

- Header

In the header you can specify the API version. If the API version is not specified the latest version will be used. You can also set the option to include request details so the request details would be returned in the response as well.

Bearer authorization is part of the header as well. You can check more information about Authentication.

- Request body

The main part of a request is query where is the specification of the sent parameters you'd like to validate or get information about. Usually at least one parameter of the query is required with some exceptions.

Options is the second most important part of the query. In this object you will find various options that influence how the validator would behave. Usually there is a specification of datascopes and some format options.

CustomId & client are optional and serve the purpose of identification and data quality in the response.

curl --request POST \
     --url https://api.foxentry.com/email/validate \
     --header 'Api-Version: 2.0' \
     --header 'Foxentry-Include-Request-Details: true' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "request": {
    "query": {
      "email": "[email protected]"
    },
    "options": {
      "validationType": "extended",
      "acceptDisposableEmails": true,
      "acceptFreemails": true
    },
    "client": {
      "location": {
        "lat": 50.0628,
        "lon": 13.9271
      },
      "ip": "127.0.1.1",
      "country": "CZ"
    },
    "customId": "customer567914"
  }
}
'

Response structure

- Response body

Status of the response is the first thing you'll come across. If your request was processed without any problem you will see status 200. All the other status codes are listed here.

The request object returns information about the initial request and query based on the Foxentry-Include-Request-Details parameter.

The response object consists of three parts: result, resultCorrected and suggestions. Each part share similar structure: Validity information, errors/fixes, data. Result is the evaluation of the sent query and contains proposal, which indicates how you should process the response on your end. If the proposal is valid or invalid, resultCorrected and suggestions would be empty. If the proposal is any other state (validWithSuggestion, invalidWithCorrection, etc..) those reponse parts would not be empty. Basically the resultCorrected is the corrected version of the sent query and suggestions are alternatives suggested fo the sent query.

{
  "status": 200,
    "request": {
    "endpoint": "email/validate",
    "code": "uNVx1TnkfLCwYwdUbOKBTzZfeJCBD2",
    "customId": "customer567914",
    "query": {
      "email": "[email protected]"
  },
  "response": {
    "result": {
      "isValid": false,
      "proposal": "invalidWithCorrection",
      "data": {
        "user": "p.novak",
        "domain": "gamil.com",
        "email": "[email protected]"
      },
      "flags": {
        "isCatchAllServer": false,
        "isDisposableEmailAddress": true,
        "isFreemail": false
      },
      "errors": [
        {
          "group": "VALUE",
          "type": "INVALID",
          "subtype": null,
          "severity": "critical",
          "relatedTo": [
            "email"
          ],
          "description": "Value is not valid."
        }
      ]
    },
    "resultCorrected": {
      "isValid": true,
      "data": {
        "user": "p.novak",
        "domain": "gmail.com",
        "email": "[email protected]"
      },
      "flags": {
        "isCatchAllServer": false,
        "isDisposableEmailAddress": false,
        "isFreemail": true
      },
      "errors": [],
      "fixes": [
        {
          "group": "VALUE",
          "type": "CHANGED",
          "subtype": "TYPO",
          "data": {
            "typeFrom": "email",
            "type": "email",
            "valueFrom": "[email protected]",
            "value": "[email protected]"
          }
        }
      ]
    },
    "suggestions": []
  },
  "errors": []
}