IDMaml
Document v1.5.0 Updated: Thursday, October 16, 2025
Welcome to the IDMaml RESTful API. You can use our API to access all of IDMaml's services.
TEST URL: {{API_URL}} (All the examples in this documentation are based on Test Environment)
Overview
IDMaml is designed to help minimize the risks associated with money laundering and other illegal activities.
IDMaml platform and risk-mitigation solutions will help your organization build a robust compliance program while substantially reducing fraud and loss.
Getting Started
If you have any questions or comments, please let us know via our Support Portal.
Knowledge Base
COMMUNICATION METHODOLOGY
The IDMaml API methodology is organized into four main sections:
- End-Point Test Method enables you to verify the accessibility of our API.
- Authentication Test Method enables you to verify the validity of the assigned credentials.
- Token Generation Method enables you to generate the access token using the provided credentials. The time period that the Token will be valid is determined by IDMERIT.
- Verification Method enables you to perform verifications and retrieve results as:
- Match
- Partial Match
- No Match
AUTHENTICATION METHODOLOGY
As stated above, the IDMaml API authentication framework is built upon token-based authentication:
- The Username and Password provided by IDMERIT to the Client.
- The user and password posted to IDMaml API via to request the API to receive an encoded access Token.
- This token must be used in all subsequent Authorization headers from the Client side API.
Date Of Birth Format
YYYY-MM-DD
Gender
| Gender Options | |||
|---|---|---|---|
| female | f | ||
| male | m | ||
Country Code Format
We support only ISO 3166-1 alpha 2 country codes. Please visit this link to know more about country codes
ERROR CODES
HTTP Error Codes
| Code | Description |
|---|---|
| 200 - OK | The request was successful. If you are getting unexpected results, please check any Status or Error messages that have been returned in the response. If you believe there may be a problem, please raise a ticket with our Support team at https://idmerit.freshdesk.com/support/tickets/new. |
| 400 - Bad Request | The request could not be understood by the server. Please ensure the request is in the appropriate format and all necessary headers have been included. |
| 401 - Unauthorized | The request requires user authentication. Please ensure that valid authentication credentials are included with the request. Access is denied due to invalid or missing credentials. |
| 403 - Forbidden | The request was valid, but the requestor does not have appropriate permissions. Please ensure your username is correct and your access token is still valid. If your access token has expired, you may need to reauthenticate your credentials to get a new token. |
| 404 - Not Found | The requested resource could not be found on the server. Please verify the URL is correct and that the resource exists. The server has not found anything matching the request URI. |
| 415 - Unsupported Media Type | The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format. |
| 500 - Internal Server Error | There was a back-end error when processing the request. Please ensure your request is in the correct format and retry. If you receive this error again, please raise a ticket with our Support team at https://idmerit.freshdesk.com/support/tickets/new. |
| 503 - Service Unavailable | This error occurs when the data source required for screening or analysis is temporarily unavailable or takes longer than expected to process. It typically indicates that the system is still aggregating or analyzing information from multiple external or internal sources. |
| 522 - Origin Connection Time-out | There was a back-end error when processing the request. Please resubmit the request. If you receive this error again, please raise a ticket with our Support team at https://idmerit.freshdesk.com/support/tickets/new. |
SOURCE/OTHER ERRORS
Please contact our support team at https://idmerit.freshdesk.com/support/tickets/new
API Description
Ping Test
curl -X GET \
-H 'Content-Type: application/json' \
'{{API_URL}}/v1.4/ping'{
"status": true,
"status_code": 200,
"message": "Successfully Connected.",
}
Content-Type: application/jsonGenerate Token
| Key | Value | |
|---|---|---|
| username |
{{username}} |
required |
| password |
{{password}} |
required |
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'username={{username}}' \
-d 'password={{password}}' \
'{{API_URL}}/v1.4/genToken'{
"status": true,
"status_code": 200,
"issued": "{{issued}}",
"expires": "{{expires}}",
"access_token": "{{access_token}}",
"token_type": "bearer",
"username": "{{username}}",
}
Content-Type: application/jsonCheck Token / Authentication
curl -X GET \
-H 'Authorization: Bearer {{token}}' \
'{{API_URL}}/v1.4/auth'{
"status": true,
"status_code": 200,
"message": "Token is valid.",
"expired_at": "2022-08-01 23:59:59",
}
Content-Type: application/jsonPerson Verification Service
The required fields to perform a match are:
Other fields you are able to match against are:
| Key | Value | |
|---|---|---|
| request_id |
{{request_id}} |
required |
| first_name |
{{first_name}} |
required |
| last_name |
{{last_name}} |
required |
| middle_name |
{{middle_name}} |
optional |
| gender |
{{gender}} m / M / f / F / male / MALE / female / FEMALE |
optional |
| dob |
{{dob}} yyyy-mm-dd |
optional |
| age |
{{age}} |
optional |
| address |
{{address}} |
optional |
| city |
{{city}} |
optional |
| state |
{{state}} |
optional |
| zip |
{{zip}} |
optional |
| country |
{{country}} |
optional |
| name_type |
{{name_type}} p / P / c / C |
required |
*Please enter either age or dob
Example
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded ' \
-H 'Authorization: Bearer {{token}}' \
-d 'request_id={{request_id}}' \
-d 'first_name={{first_name}}' \
-d 'last_name={{last_name}}' \
-d 'middle_name={{middle_name}}' \
-d 'gender={{gender}}' \
-d 'dob={{dob}}' \
-d 'age={{age}}' \
-d 'address={{address}}' \
-d 'city={{city}}' \
-d 'state={{state}}' \
-d 'zip={{zip}}' \
-d 'country={{country}}' \
-d 'name_type={{name_type}}' \
'{{API_URL}}/v1.4/verify'{
"status": true,
"status_code": 200,
"data": {
"first_name": "{{first_name}}",
"last_name": "{{last_name}}",
"middle_name": "{{middle_name}}",
"dob": "{{dob}}",
"gender": "{{gender}}",
"city": "{{city}}",
"state": "{{state}}",
"country": "{{country}}",
"address": "{{address}}"
},
"transaction_id": "16300592946128bb1ec25ecuyMrz",
"request_id": "00000",
}
Content-Type: application/jsonCompany Verification Service
The required fields to perform a match are:
Other fields you are able to match against are:
| Key | Value | |
|---|---|---|
| request_id |
{{request_id}} |
required |
| company_name |
{{company_name}} |
required |
| name_type |
{{name_type}} p / P / c / C |
required |
| address |
{{address}} |
optional |
| city |
{{city}} |
optional |
| state |
{{state}} |
optional |
| zip |
{{zip}} |
optional |
| country |
{{country}} |
optional |
Example
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer {{token}}' \
-d 'request_id={{request_id}}' \
-d 'company_name={{company_name}}' \
-d 'name_type={{name_type}}' \
-d 'address={{address}}' \
-d 'city={{city}}' \
-d 'state={{state}}' \
-d 'zip={{zip}}' \
-d 'country={{country}}' \
'{{API_URL}}/v1.4/verify'{
"status": true,
"status_code": 200,
"data": {
"company_name": "{{company_name}}",
"city": "{{city}}",
"state": "{{state}}",
"country": "{{country}}",
"zip": "{{zip}}",
"address": "{{address}}"
},
"transaction_id": "xxxxxxxxxxxxxxxxxxxxxxx",
"request_id": "00001",
}
Content-Type: application/jsonPerson Info(JSON) Service
The required fields to perform a match are:
Other fields you are able to match against are:
| Key | Value | |
|---|---|---|
| request_id |
{{request_id}} |
required |
| first_name |
{{first_name}} |
required |
| last_name |
{{last_name}} |
required |
| dob |
{{dob}} yyyy-mm-dd |
optional |
| age |
{{age}} |
optional |
| middle_name |
{{middle_name}} |
optional |
| response_type |
{{response_type}} json / JSON |
optional |
| name_type |
{{name_type}} p / P / c / C |
required |
| monitoring |
{{monitoring}} (string) true / false |
optional |
*Please enter either age or dob
Example
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer {{token}}' \
-d 'request_id={{request_id}}' \
-d 'first_name={{first_name}}' \
-d 'last_name={{last_name}}' \
-d 'dob={{dob}}' \
-d 'age={{age}}' \
-d 'middle_name={{middle_name}}' \
-d 'response_type={{response_type}}' \
-d 'name_type={{name_type}}' \
-d 'monitoring={{monitoring}}' \
'{{API_URL}}/v1.4/info'{
"status": true,
"status_code": 200,
"data": {
"name": "{{person full name}}",
"id": "{{number}}",
"status": "{{status}}",
"dob": "{{dob}}",
"type": "{{type}}",
"riskscore": "{{riskscore}}",
"registered_events": "{{registered_events}}",
"addresses": "{{addresses}}",
"attributes": "{{attributes}}",
"sourceurl": "{{sourceurl}}",
"aliases": "{{aliases}}",
"positions": "{{positions}}",
"relation": "{{relation}}",
"source": "{{source}}"
},
"transaction_id": "xxxxxxxxxxxxxxxxxxxxxxx",
"request_id": "00001",
}
Content-Type: application/jsonCompany Info(JSON) Service
The required fields to perform a match are:
Other fields you are able to match against are:
| Key | Value | |
|---|---|---|
| request_id |
{{request_id}} |
required |
| company_name |
{{company_name}} |
required |
| name_type |
{{name_type}} p / P / c / C |
required |
| response_type |
{{response_type}} json / JSON |
optional |
| monitoring |
{{monitoring}} true / false / |
optional |
Example
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer {{token}}' \
-d 'request_id={{request_id}}' \
-d 'company_name={{company_name}}' \
-d 'name_type={{name_type}}' \
-d 'response_type={{response_type}}' \
-d 'monitoring={{monitoring}}' \
'{{API_URL}}/v1.4/info'{
"status": true,
"status_code": 200,
"data": {
"name": "{{company name}}",
"id": "{{number}}",
"status": "{{status}}",
"type": "{{type}}",
"riskscore": "{{riskscore}}",
"registered_events": "{{registered_events}}",
"addresses": "{{addresses}}",
"attributes": "{{attributes}}",
"sourceurl": "{{sourceurl}}",
"aliases": "{{aliases}}",
"positions": "{{positions}}",
"relation": "{{relation}}",
"source": "{{source}}"
},
"transaction_id": "xxxxxxxxxxxxxxxxxxxxxxx",
"request_id": "00001",
}
Content-Type: application/jsonPerson Info(PDF) Service
The required fields to perform a match are:
Other fields you are able to match against are:
| Key | Value | |
|---|---|---|
| request_id |
{{request_id}} |
required |
| first_name |
{{first_name}} |
required |
| last_name |
{{last_name}} |
required |
| dob |
{{dob}} yyyy-mm-dd |
optional |
| age |
{{age}} |
optional |
| middle_name |
{{middle_name}} |
optional |
| response_type |
{{response_type}} pdf / PDF |
optional |
| name_type |
{{name_type}} p / P / c / C |
required |
| monitoring |
{{monitoring}} (string) true / false |
optional |
*Please enter either age or dob
Steps to convert the API response to PDF
- Copy the Response of the API
- Pass it to JSON Decoder to ensure proper JSON
- Take the Data
- Pass it through Base64 Decoder
- Save the result as PDF
Example
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer {{token}}' \
-d 'request_id={{request_id}}' \
-d 'first_name={{first_name}}' \
-d 'last_name={{last_name}}' \
-d 'dob={{dob}}' \
-d 'age={{age}}' \
-d 'middle_name={{middle_name}}' \
-d 'response_type={{response_type}}' \
-d 'name_type={{name_type}}' \
-d 'monitoring={{monitoring}}' \
'{{API_URL}}/v1.4/info'{
"status": true,
"status_code": 200,
"data": {{base 64 encode string}},
"message": "person found.",
"expired_at": "2022-08-01 23:59:59",
"transaction_id": "xxxxxxxxxxxxxxxxxxxxxxx",
"request_id": "00001",
}
Content-Type: application/jsonCompany Info(PDF) Service
The required fields to perform a match are:
Other fields you are able to match against are:
| Key | Value | |
|---|---|---|
| request_id |
{{request_id}} |
required |
| company_name |
{{company_name}} |
required |
| name_type |
{{name_type}} p / P / c / C |
required |
| response_type |
{{response_type}} pdf / PDF |
optional |
| monitoring |
{{monitoring}} true / false |
optional |
Response>>JSON Decode>>Take the data>>Base64 decode>>Save the response from decode to PDF
Steps to convert the API response to PDF
- Copy the Response of the API
- Pass it to JSON Decoder to ensure proper JSON
- Take the Data
- Pass it through Base64 Decoder
- Save the result as PDF
Example
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer {{token}}' \
-d 'request_id={{request_id}}' \
-d 'company_name={{company_name}}' \
-d 'name_type={{name_type}}' \
-d 'response_type={{response_type}}' \
-d 'monitoring={{monitoring}}' \
'{{API_URL}}/v1.4/info'{
"status": true,
"status_code": 200,
"data": {{base 64 encode string}},
"message": "person found.",
"expired_at": "2022-08-01 23:59:59",
"transaction_id": "xxxxxxxxxxxxxxxxxxxxxxx",
"request_id": "00001"
}
Content-Type: application/jsonEvent Attributes
The Event Attributes defines how IDMaml categorizes and classifies risk-related information detected during entity screening. It has structure and metadata for screening events. These event attributes helps client to understand why an alert was generated and what kind of risk it represents.
| Level | Description | Examples |
|---|---|---|
| Risk Areas | The high-level risk domain relevant to AML or financial crime | Financial Crime, Terror Financing, Fraud, Corruption |
| Category | A specific classification within a risk area | Bribery, Money Laundering |
| Subcategory | A finer-grained description under a category | Political Bribery, Corporate Fraud |
| Event Stage | Where that event currently stands in its real-world progression | Arraign, Conviction, Investigation, Acquittal |
Risk scoring Framework
Our solutions’ scoring system is built upon a multi-dimensional, dynamic scoring model that integrates several critical factors to deliver a single comprehensive relevance score. This relevance score helps prioritize and contextualize adverse media findings with precision and adaptability.
Core Components of the Scoring Model
-
Risk Impact Categories
Each event is assigned a risk impact level (low to critical), which reflects the severity and potential consequences of the issue described. This categorization considers factors such as legal exposure, reputational harm, and regulatory implications, derived from nature and keywords within the content.
-
Event Development Stages
This dimension captures the progression of an event through various phases, from preliminary mentions to final legal or regulatory resolutions. It reflects the maturity and credibility of the reported issue, helping users understand whether a risk is emerging, active, or resolved.
-
Entity Match Score
Our system evaluates how closely the content is related to the specific entity (individual or organization) under review. This score accounts for:
- Name variations and aliases
- Contextual linkage in the article
- Location, date of birth, or other identifying details
The higher the entity match score, the greater the confidence that the media content is relevant and applicable to the subject
The dynamic scoring engine uses these to calculate an overall relevance score, which quantifies the likelihood that a given media article or event is:
- Materially related to the entity under review
- Indicative of a risk that merits attention based on severity and progression
- Aligned with the client’s configured risk tolerance and filtering preferences
Relevance Score=f(Risk Impact Level, Event Stage, Entity Match Score)
- Where f is a proprietary method developed and continuously refined to balance accuracy and recall, ensuring high-value results.
- This composite relevance score produced by our scoring engine is expressed as a numerical value between 0 and 100, representing the system’s confidence that a given media article or event is materially relevant and actionable for the entity under review.
Monitoring System – Webhook
IDMERIT offers an optional API webhook that allows IDMeirt to automatically send Monitoring alerts to client endpoints. This convenience feature removes the need for clients to code for extra API calls to call back into IDMERIT to retrieve alerts.
To automatically receive alerts, IDMERIT can be configured to point to a client endpoint (webhook). For integration, IDMERIT supports REST API endpoints with login in credentials for added security.
How does IDMaml Monitoring Works
IDMaml’s Monitoring System provides continuous and automated tracking of entities (individuals or organizations) against multiple risk data sources, including Adverse Media, Sanctions Lists, Politically Exposed Persons (PEPs), and Watchlists.
Once an entity is onboarded to the monitoring system, it is continuously monitored for any new events or updates that may impact its risk profile.
The system automatically detects, evaluates, and notifies clients through webhooks at scheduled updates.
Monitoring Frequency and Scheduling
The monitoring frequency defines how often each entity is rechecked against global data sources for updates, such as new sanctions, watchlist entries, or adverse media mentions. IDMERIT AML engine automatically re-checks the entity at the defined interval.Available Frequency Modes.
| Frequency | Description | Typical Use Case |
|---|---|---|
| Daily | Entity is automatically re-screened once every 24 hours | High Risk |
| Weekly | Re-screening occurs once every 7 days. | Medium Risk |
| Monthly | Re-screening occurs once every 30 days. | Low Risk |
Data Sources
| Type | Description |
|---|---|
| Sanctions | Global and regional sanctions lists maintained by regulatory authorities |
| PEP Lists | Structured datasets of politically exposed persons, relatives, and associates |
| Watchlists | Law enforcement, regulatory, and criminal watchlists |
| Adverse Media | Global News and media coverage linking entities to risk events |
| Court Cases | Court Cases Legal records of proceedings and judicial actions |
Web-hook Setup Process:
Regarding the setup of the web-hook, please follow the steps provided below (this may vary depending on the architecture and programming language you are using):
- Set up a web server, such as Tomcat or Nginx, to handle incoming requests.
- Define a specific endpoint on your server where the web-hook payload will be delivered, like https://alert.yourcompanydomain.com or https://webhook.yourcompanydomain.com
- Develop an application or API that can accept JSON payloads in the “application/json” format.
- Implement a Basic Authentication, by configuring a username and password to ensure secure communication.
- Process the received data according to your application’s requirements.
- Send a response back to us to confirm the successful receipt of the payload. For example, return
a JSON array (mentioned below) upon successful processing. Similarly, for error, you can send a
JSON array with status code and message.
{"status": 200, "message": "successful"} - Provide the Endpoint URL to us so we can configure our systems to send payloads to your specified endpoint.
- As an additional fail-safe measure for web-hook notifications, please create a dedicated email address such as alerts@yourcompanydomain.com. We will configure it to send alerts alongside the web-hook integration.
Post Web-hook Setup Steps:
After you’ve set-up web-hook, we would require you to send us below details:
- Web-hook URL (“https://alert.yourcompanydomain.com” or “https://webhook.yourcompanydomain.com”)
- Authentication: Basic Auth
- Parameters:
- username
- password
- [Optional] email-id: (like “alerts@yourcompanydomain.com”)
Once we’ve above details, we will be performing our QC tests to conclude if all the parameters are set before configuring it to our systems.
IDMERIT Push notification for the entity monitoring:
FAQs:
Q) In the event that our API / Web-hook subscriber is unavailable and the web-hook is triggered, what process is implemented around error handling and re-trying? If your service cannot post to our receiver, what happens to that request? Is it lost or is there any retry paradigm?
A) In the event that the web-hook API fails or becomes unreachable, we have implemented a fail-safe method. We send alerts through two channels: the Web-hook API and email. We therefore recommend creating a dedicated email address to receive all the alerts.
Q) What schedule, event, trigger causes the web-hook to be initiated?
A) The monitoring alerts are not scheduled. They are triggered whenever an event occurs. However, these alerts/notifications are pushed to client’s webhook APIs on daily basis, according to configured time-zone.
Q) I understand that the web-hook supports basic auth. Is this mandatory?
A) Yes, we have made basic authentication mandatory for security purposes.
Q) What is the response when an entity is added in the Sanction’s List?
A) If an entity is added in the Sanction’s List, event response would include codes like “SAN”, “SNX”, “WLT”, etc to track such events.
Q) What is the response when an entity is removed from the Sanction’s List?
A) ) In an event when entity is removed from Sanction’s List, it would include event with code “FOF”, “FOS”. This event code indicates that the entity was a former Sanctioned entity.