HomepageDashboard

Authentication & format

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 is br)

📘

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 be True, and the HTTP code will always be 200.
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 be 400.
The response will also contain the property error_type and error_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"
}