IDMtrust
V2.1 Updated: Friday 21st August, 2024
Introduction
IDMtrust is designed to analyze a user’s digital footprint-traces left behind when they interact with digital products, whether during registration, access, or usage. By leveraging this information, IDMtrust provides instant insights into the quality and reliability of online customers.
Our solution evaluates hundreds of data points from a user’s email address, phone number, and IP address to generate a comprehensive risk score, helping you assess the potential risk associated with each user.
Getting Started
This quick start guide will help you begin integrating our API into your application with just a few easy steps.
Sandbox Base URL and Version:
Production Base URL and Version:
Step 1: Get Your API Credentials To begin, you’ll need to generate a token using your assigned username and password. This token will be required to authenticate all your API requests.
Step 2: Make Your First Request With your token ready, you can start making API calls. Simply include the token in the `Authorization` header of your requests to access the available service methods.
Step 3: Explore the API Refer to the full documentation to explore the variety of insights available for each input.
Step 4: Handle Rate Limits and Errors Be mindful of our rate limits and ensure that your application properly handles any errors.
Authentication
To access the IDMtrust API, you`ll need to authenticate by generating a bearer token using your assigned credentials. This token will be used for all subsequent API requests. Below are the steps to authenticate and test your token.
Generate a TokenTo generate a token, make a POST request to the genToken endpoint. You`ll need to provide your allotted username and password in the request body
Sample ResponseUpon a successful request, you will receive a response with the generated token and additional details.
- access_token: The bearer token to be used in subsequent API requests
- expires: The expiration date and time of the token.
- username: The username associated with the token.
After obtaining your token, you can test its validity by making a GET request to the auth endpoint.
Sample ResponseA successful response will confirm that your token is valid and provide details about its expiration.
- message: Indicates that the token is valid.
- expired_at:The expiration date and time of the token
curl --location https://{{BaseURL}}/{{Version}}/genToken \
--header Content-Type: application/x-www-form-urlencoded \
--data-urlencode username=USERNAME \
--data-urlencode password=PASSWORD
{
"result": true,
"status": 200,
"issued": "2023-08-06 15:31:10 (GMT)",
"expires": "2024-12-31 23:59:59 (GMT)",
"access_token": "TOKEN",
"token_type": "bearer",
"username": "USERNAME"
}
curl --location https://{{BaseURL}}/{{Version}}/auth \
--header Authorization: Bearer TOKEN
{
"result": true,
"status_code": 200,
"message": "Token is valid.",
"expired_at": "2024-12-31 23:59:59 (GMT)"
}
API Endpoints
The IDMtrust API provides a single, versatile endpoint to analyze user data based on email, phone number, and IP address. Below are the details for interacting with this endpoint, including the request structure, response structure, and an explanation of the response data.
Endpoint: /service
- Method: POST
- URL: https://{{BaseURL}}/{{Version}}/service
To interact with this endpoint, send a POST request with the following parameters:
- Headers:
- Content-Type: application/x-www-form-urlencoded
- Authorization: Bearer {{TOKEN}}
- Body Parameters
- request_id: (Mandatory) A unique identifier for your request, used for tracking.
- Any one is mandatory
- email: The email address you wish to analyze.
- phone: The phone number you wish to analyze, in international format.
- ip: The IP address you wish to analyze.
A successful request returns a JSON response containing detailed insights for the provided email, phone number, and IP address.
Response Body Explanation- result: A Boolean indicating if the request was successful.
- status_code: The HTTP status code of the response.
- message: A brief message describing the outcome of the request.
- data: An object containing detailed insights.
- fraud_score: A comprehensive score representing the risk level based on the analysis.
- Email Details:
- email: The analyzed email address.
- score: Risk score associated with the email.
- email_status: : Indicates if the email is any of the following:
- Deliverable: The address is valid and can receive mail.
- Invalid: The address cannot receive mail.
- Unknown: The status of the address can`t be determined because the server is unreachable.
- Typo: The address is likely wrong due to a typing error.
- Accept-all:The address accepts all mail but we can`t confirm if the account is active.
- Disposable: The address is a temporary email.
- Spam-trap: The address is inactive and used to catch spam.
- Spam-track: Same as spam-trap.
- domain_details: : Information about the email`s domain, including whether it`s disposable, free, and other related attributes.
- account_details: :Detailed analysis of the email`s account components such as length, number of dots, vowels, consonants, and parsed names.
- breach_details: : Information on whether the email has been involved in any data breaches.
-
Phone Details:
- number: : The analyzed phone number.
- valid: : Boolean indicating if the phone number is valid.
- type: : Type of phone number (e.g., mobile, landline).
- country_code: : The country code associated with the phone number.
- score: : Risk score associated with the phone number.
- disposable: : Indicates if the phone number is disposable.
- portability_details: : Information about the phone number`s portability history.
- original_carrier: : The original carrier of the phone number.
- current_carrier: : The current carrier of the phone number.
- breach_details: : Information on whether the phone number has been involved in any data breaches.
- IP Details:
- ip: The analyzed IP address.
- country_code: The country code associated with the IP address.
- score: Type of phone number (e.g., mobile, landline).
- city: The city associated with the IP address.
- connection_speed: The speed of the connection (e.g., broadband, fiber).
- connection_type: : Type of connection (e.g., Content Delivery Network).
- isp: The Internet Service Provider for the IP address.
- timezone: The timezone of the IP address.
- zip: The ZIP code associated with the IP address.
- mobile: Boolean indicating if the IP address is associated with a mobile connection.
- vpn: Boolean indicating if the IP is associated with a VPN.
- proxy: Boolean indicating if the IP is associated with a proxy.
- tor: Boolean indicating if the IP is associated with Tor.
- relay: Boolean indicating if the IP is a relay.
- hosting: Boolean indicating if the IP is associated with hosting services.
- black_list_count: The number of blacklists the IP address is on.
- xbl_count: The number of spam-related blacklists the IP is on.
- css_count: The number of Content Security Policy lists the IP is on.
- xbl_in_days: Days since the IP was listed on an XBL.
- transaction_id: A unique identifier for the transaction, useful for support and debugging.
- request_id: The original request ID provided, useful for tracking.
- fraud_score: A numerical score indicating the overall risk level.
- email_details: Nested object containing detailed information about the email address.
- phone_details: Nested object containing detailed information about the phone number.
- Ip_details: Nested object containing detailed information about the IP address.
curl --location https://{{BaseURL}}/{{Version}}/service \
--header Content-Type: application/x-www-form-urlencoded \
--header Authorization: Bearer {{TOKEN}} \
--data-urlencode request_id=ANY-PREFERED-REQUEST-ID \
--data-urlencode email= dummy_user@example.com \
--data-urlencode phone=+1234567890 \
--data-urlencode ip=203.0.113.0
{
"result": true,
"status_code": 200,
"message": "Data retrieved successfully",
"data": {
"fraud_score": 85,
"email_details": {
"email": "dummy_user@example.com",
"score": 60,
"email_status": "deliverable",
"domain_details": {
"disposable": true,
"disposable_provider_name": "tempmail.com",
"spamtrap": false,
"free": true,
"domain": "example.com",
"age": 5000,
"mx_is_valid": true,
"mx_provider": "example_provider.com",
"registrar": "Example Registrar, Inc.",
"registered_to": "Example LLC",
"registered": true,
"website_exists": true,
"website_exists_taxonomy": "TAXONOMY_WEBSITE_EXISTS",
"website_exists_ssl": true,
"tld": ".com",
"custom": false
},
"account_details": {
"length": 12,
"dots_count": 1,
"numbers_count": 3,
"letters_count": 9,
"symbols_count": 0,
"vowels_count": 4,
"consonants_count": 5,
"dots_ratio": 0.08,
"numbers_ratio": 0.25,
"letters_ratio": 0.75,
"symbols_ratio": 0.0,
"vowels_ratio": 0.33,
"consonants_ratio": 0.42,
"parsed_first_name": "John",
"parsed_last_name": "Doe",
"parsed_name_risk_type": "COMMON",
"parsed_name_is_valid": true,
"stop_words": false,
"related_options": "jane@example.com"
},
"breach_details": {
"count": 1,
"first_breach": "2019-06-15",
"last_breach": "2019-06-15",
"list": "Databreach#1,2019-06-15|Databreach#2,2021-08-10"
}
},
"phone_details": {
"number": "1234567890",
"valid": true,
"type": "mobile",
"country_code": "US",
"score": 30,
"disposable": true,
"disposable_provider_name": "tempmobile.com",
"suspicious_format": false,
"portability_details": {
"status": true,
"first": "2022-01-01",
"last": "2022-06-01",
"times": 1
},
"original_carrier": "Example Carrier",
"current_carrier": "Example Carrier",
"caller_type": "BUSINESS",
"caller_company_name": "Example Corp",
"breach_details": {
"count": 1,
"first_breach": "2018-01-01",
"last_breach": "2023-01-01",
"list": "Databreach#1,2018-01-01"
}
},
"ip_details": {
"ip": "203.0.113.0",
"country_code": "US",
"score": 40,
"city": "Sample City",
"connection_speed": "broadband/cable/fiber",
"connection_type": "Fixed Line",
"isp": "Example ISP",
"timezone": "America/New_York",
"zip": "12345",
"mobile": false,
"vpn": false,
"vpn_name": false,
"proxy": true,
"proxy_name": "Example Proxy",
"proxy_type": "datacenter",
"tor": false,
"relay": false,
"hosting": false,
"black_list_count": 1,
"xbl_count": 0,
"css_count": 0,
"xbl_in_days": 10,
"css_in_days": 0
}
},
"transaction_id": "abcdefg-12345-hijklmn-67890",
"request_id": " ANY-PREFERED-REQUEST-ID "
}
Error Handling
When interacting with the IDMtrust API, you may encounter various HTTP status codes indicating the success or failure of your requests. Understanding these codes will help you troubleshoot and resolve issues more effectively. Below is a list of common error codes and their meanings:
| Status code | Description | Resolution |
|---|---|---|
| 400 Bad Request | The request could not be understood or was missing required parameters. | Check the request structure and ensure all required fields are included and correctly formatted. |
| 401 Unauthorized | Authentication failed or the user does not have permissions for the requested operation. | Ensure your API token is valid and included in the request. If necessary, generate a new token. |
| 403 Forbidden | The server understood the request, but refuses to authorize it. | Verify your permissions and ensure you have the appropriate access rights to perform the requested operation. |
| 415 Unsupported Media Type | The server cannot process the request because the media type of the request payload is not supported. | Ensure the Content-Type header matches the expected format and verify the request body is in the correct format. |
| 500 Internal Server Error | An unexpected error occurred on the server. | Retry the request after some time. If the issue persists, contact support with details of your request and response. |
| 502 Bad Gateway | The server received an invalid response from an upstream server while trying to fulfill the request. | Retry the request. If the issue continues, it may indicate a temporary problem with the API`s infrastructure. |
| 504 Gateway Timeout | The server did not receive a timely response from an upstream server or the request timed out. | Retry the request after some time. If the issue persists, it may be related to server performance or network conditions. |
When an error occurs, the API will typically return a response with a status code and an error message. Below is a generic example of an error response:
- result: Indicates whether the request was successful (false for errors).
- status_code: The HTTP status code of the response.
- message: A brief description of the error.
- validation: Additional details about the error, such as which fields caused the problem.
- Log Errors: Always log errors with as much detail as possible, including request parameters and full error responses.
- Graceful Degradation: Implement fallback mechanisms to handle errors gracefully in your application, providing users with meaningful messages rather than raw error codes.
- Retry Logic: For transient errors like 500, 502, or 504, implement retry logic with exponential backoff to handle temporary server issues.
- Contact Support: If you`re unable to resolve an issue, gather all relevant details, including request and response data, and contact support for assistance.
{
"result": false,
"status_code": 400,
"message": "Request validation error.",
"validation": {
"email": [
"The email field must not be greater than 100 characters"
],
"phone": [
"Please enter a valid phone number with a valid country dialing code."
],
"ip": [
"The IP field must be a valid IP address."
]
}
}
Rate Limiting
To ensure fair usage and maintain the performance of the IDMtrust API, we enforce a rate limit of 100 requests per minute for all users. If your application requires a higher request rate, you can submit a formal request to have your account moved to a higher tier.
Handling Rate Limits- Standard Tier: By default, the account is limited to 100 requests per minute. If you exceed this limit, additional requests will be throttled and you will receive a 429 Too Many Requests response.
- Higher Tier: If your application consistently requires more than 100 requests per minute, you may request to upgrade to a higher tier where our support team will evaluate the transaction rates and provide approval. This allows us to adjust the rate limit to better accommodate your needs.
To request a higher rate limit, please contact our support team with details about your application and expected usage. We will review your request and, if approved, move your account to a higher tier with an increased request allowance.
Support
We are committed to providing you with the best possible support as you integrate and use the IDMtrust API. Whether you need help troubleshooting an issue, have questions about the API, or require assistance with your account, our support team is here to help.
Getting Help- Documentation: Before reaching out, please review our comprehensive documentation, which covers common use cases, error handling, and best practices. Many questions can be answered by consulting the relevant sections of this guide.
- Email Support: For direct assistance, you can contact our support team via email at support@idmerit.com. Please include as much detail as possible about your issue, including any relevant request and response data, to help us resolve your issue more efficiently.
- Support Portal: Visit our Support Portal https://idmerit.freshdesk.com/support/tickets/new to submit a support ticket, check the status of an existing request, or browse our knowledge base for articles and FAQs.