Our API is a breeze to use and was built with developers' comfort in mind. Let’s get into it.
API Authentication
Our API base URL is: https://api.defastra.com
Our API requires HTTPS
, and only accept the POST
method.
Each request sent to Defastra API requires 2 mandatory headers:
- X-API-KEY:
your_api_key
(can be found here) - Content-Type:
application/x-www-form-urlencoded
For better performance, we also advise using those 2 optional headers:
- Connection:
keep-alive
(as TLS takes time to initiate the first connection handshake, it is advised to keep the connection open) - Accept-Encoding:
gzip, deflate, br
(this will indicate our server to compress the response - preferred encoding isbr
)
Note
You can create as many API keys as you need from the dashboard, and give them a name.
API access is automatically enabled on your Defastra account when you sign-up.
It can be deactivated as a whole from your API management page.
Request format
All your requests to our API will always be using the POST
method.
Each request body needs to be formatted using the application/x-www-form-urlencoded
format (set in the Content-Type
header).
Here is an example of a request made to our Deep Email Check API endpoints:
POST https://api.defastra.com/deep_email_check
Host: api.defastra.com
Connection: keep-alive
Accept-Encoding: gzip, deflate, br
X-API-KEY: 0bc365bdb7f1e7c587a0ec5e4d0b39e94b3193e758250449
Content-Type: application/x-www-form-urlencoded
[email protected]&timeout=extensive&label=SIMPLE%20TEST
The body is properly formatted.
Important
As you can see, the
label
parameter in the example has its value URL encoded.
Response format
All the responses from our API will be encoded in JSON
, and our response will contain the appropriate Content-Type: application/json
header.
Our response will always contain the boolean status
property, indicating if the request failed or succeeded.
The status
property should always be checked before reading the response to determine if everything went well. Please read our Error handling page.
Depending on the status
, the response will contain additional properties, see below:
The request was successful
The
status
property will always beTrue
, and the HTTP code will always be200
.
The response will also contain the following properties:
wallet
, a decimal number indicating how much funds are remaining in your wallet (this property will not be returned to team members)request_id
, a randomly generated string used to identify the request. It can be stored on your side and used to find results in the Observer.- And a 3rd property, being the name of the endpoint. It is an object containing the actual data of the response. For example, the property will be named
deep_email_check
if you are using the/deep_email_check
endpoint.
The request failed
The status property will always be
False
, and the HTTP code will always be400
.
The response will also contain the propertyerror_type
anderror_message
.
Please refer to our Error handling page.
Raw responses example
The JSON
returned a successful response using our Deep Email Check API:
{
"status": true,
"request_id": "D42B89762F3E715996331E942F12B8F4",
"deep_phone_check": {
"risk_level": "extreme",
"risk_score": 100,
"checks": {
"PHONE_DISPOSABLE": {
"result_type": "risk",
"detail": "Phone number was found on various free temporary/disposable SMS services: https://receive-smss.com/"
},
"PHONE_CARRIER": {
"result_type": "risk",
"detail": "The carrier of this phone 'T-Mobile Prepaid' is mostly associated with fraud"
},
"PHONE_OS": {
"result_type": "risk",
"detail": "This phone is not live on any Android or iOS device, which is unusual for the country US"
},
"PHONE_BLACKMARKET_PRESENCE": {
"result_type": "risk",
"detail": "This phone is linked to a VKontakt account, which is highly unusual for a US number, indicating a shared SIM"
},
"PHONE_DATA_BREACH": {
"result_type": "neutral",
"detail": "This phone number is not present in any data breaches"
},
"PHONE_BLACKMARKET_PATTERN": {
"result_type": "risk",
"detail": "This phone number is linked to a Telegram account named 'EscortHire Premium'. The word 'Escort' is blacklisted as it is always associated with fraud."
},
"PHONE_IS_BLACKLISTED": {
"result_type": "risk",
"detail": "This phone has been blacklisted by Tiktok"
},
"PHONE_TYPE": {
"result_type": "trust",
"detail": "The phone number type is mobile"
},
"PHONE_CONSISTENCY": {
"result_type": "neutral",
"detail": "There is no online presence data to check the HLR country consistency check."
}
},
"data": {
"phone_hlr": {
"phone_type": "MOBILE",
"prefix": "1",
"without_prefix": "2040001234",
"carrier": "T-Mobile prepaid",
"location": {
"country_name": "United-States",
"country_code": "US",
"country_iso_3": "USA",
"time_zone": -3,
"city": "Chicago",
"state": "IL",
"county": null,
"latitude": null,
"longitude": null
}
},
"phone_os": "NONE",
"phone_online_presence": {
"profile_found": 9,
"name_found": [
{
"service": "telegram",
"name": "EscortHire Premium"
}
],
"description": "In order to get the full online presence lookup report, please use our data enrichment API."
},
"phone_data_breaches": {
"breached": false,
"breach_count": 0,
"first_breach_date": null,
"what_leaked": null,
"breaches": null
}
}
},
"my_account": {
"balance": 287.39,
"wallet": 50
}
}
The response returned when there is an error is as follows:
{
"status": false,
"error_message": "This API key is invalid.",
"error_type": "INVALID_API_KEY"
}