Skip to main content

Create and manage monitoring

Requirements
  • API key
  • Services enabled on your environment (done by iDenfy's staff)
  • Finances

Creating Monitoring​

create monitoring

Authorization: API key pair
Method: POST
Endpoint: https://ivs.idenfy.com/api/v2/add-aml-user

Adding an Individual (Person) to AML Monitoring​

  1. Using an Existing Verification:
  • Send a JSON request including the scanRef from the client's previous verification.
  • Required: scanRef
  • Note: If you provide a scanRef, the system will always assume the entry is for a PERSON, regardless of any type value you might also send.
  1. Entering Details Manually:
  • Send a JSON request with the person's information.
    • Required:
    • name
    • surname
    • type (must be set to PERSON)
  • Optional:
    • nationality
    • dateOfBirth

Adding a Company to AML Monitoring​

  • Send a JSON request with the company's information.
  • Required:
    • name (Company's name)
    • country (Company's country of registration/operation)
    • type (must be set to COMPANY)
scanRef| Type: String
Explanation:

A unique string identifying a client verification on iDenfy’s side.

type| Type: String
Explanation:

Values:

  • COMPANY: Specifies the type as a company.
  • PERSON: Specifies the type as a person.
name| Type: String
Explanation:

Name of the monitored user or company.

surname| Type: String
Explanation:

Surname of the monitored user.

nationality| Type: String
Explanation:

Nationality of the monitored user.

dateOfBirth| Type: String
Explanation:

Monitored user's date of birth.

country| Type: String
Explanation:

Mandatory parameter for the COMPANY checks in alpha2/alpha3 format.

autoExpirationExtension| Type: Bool
Explanation:

The subject's monitoring will be automatically extended after the expiration date if an account has funds. If not, after updating the funds, the previous expired monitoring subjects will be extended. Default value is true.

monitorAdverseMedia| Type: Bool
Explanation:

Negative news monitoring should be part of the AML monitoring.

Creating PERSON monitoring:​

Request example - scanRef:​

{
  "scanRef": "scanRef"
}

Request example - data:​

{
  "name": "name",
  "surname": "surname",
  "dateOfBirth": "1990-01-01",
  "nationality": "LTU",
  "type": "PERSON",
  "monitorAdverseMedia": true
}

Creating COMPANY monitoring:​

{
  "name": "Company's name",
  "type": "COMPANY"
}

A successful API call returns a JSON response with monitoringId.

{
  "monitoring_id": "123456789"
}

Test monitoring creation​

Authentication

Monitoring Mode

Parameters

ID from a previous verification.

Request Body

{}

Response





Get Monitoring​


get monitoring information
Authorization: API key pair

Method: POST

Endpoint: https://ivs.idenfy.com/api/v2/get-monitoring-callback


monitoringId| Type: String
Explanation:
A unique string identifying a monitored user or company.
name| Type: String
Explanation:
Name of the monitored user or company.
surname| Type: String
Explanation:
Surname of the monitored user.
nationality| Type: String
Explanation:
Nationality of the monitored user.
dob| Type: String
Explanation:
Date of birth monitored user.
scanRefList| Type: List
Explanation:
A list of strings that are used for identifying a client's verification on iDenfy’s side.
alert_status| Type: String
Explanation:
Current status of the monitored user.


Possible values:


    

  • ALERT
    • 

  • ACCEPTED
    • 

  • DECLINED
    • 

  • PENDING
    • 

results| Type: List
Explanation:
List of check results returned from AML services.
status| Type: Object
Explanation:
The overall status of the service check.
serviceSuspected| Type: Bool
Explanation:
Indicates whether a service found a record about the person under check.
checkSuccessful| Type: Bool
Explanation:
Indicated whether an error occurred while doing a check.
serviceFound| Type: Bool
Explanation:
Indicates whether a service was found for a given country.
serviceUsed| Type: Bool
Explanation:
Indicated whether a service was used.
overallStatus| Type: String
Explanation:
A mapping string indicating overall status of the check.
serviceName| Type: String
Explanation:
The name of the service that was used to check a person.
serviceGroupType| Type: String
Explanation:
The type of the service that was used. It is always AML.
uid| Type: String
Explanation:
A unique identifier for a request. NOTE that it is unique only in one request scope. It is not unique globally. This parameter is only useful when doing multi-person checks.
errorMessage| Type: String
Explanation:
In case of an error in the checking process a human readable error message is given.
data| Type: List
Explanation:
Data returned from services.
name| Type: String
Explanation:
The name of the person in the service's database.
surname| Type: String
Explanation:
The surname of the person in the service's database.
nationality| Type: String
Explanation:
The nationality of the person in the service's database.
dob| Type: String
Explanation:
The date of birth of the person in the service's database.
suspicion| Type: String
Explanation:
Tells the kind of the suspicion.


Possible values:


    

  • PEPS
    • 

  • SANCTION
    • 

  • INTERPOL
    • 

  • OTHER
    • 

reason| Type: String
Explanation:
Tells the reason of the kind of the suspicion.
score| Type: Integer
Explanation:
Confidence coefficient that the information about the person is true.
lastUpdate| Type: String
Explanation:
Date of when the record was last updated.
isPerson| Type: Bool
Explanation:
Indicates whether the record is about a PERSON or COMPANY.
isActive| Type: Bool
Explanation:
Indicated whether a record is active.
checkDate| Type: String
Explanation:
Date and time of when AML name service was checked.
whitelisted| Type: Bool
Explanation:
Boolean indicator if the entry is whitelisted.
additional fields
companyId, beneficiaryId, comments, pepsStatus,status_set_by, status_set_at, adverseMediaStatus, and sanctionsStatus also appear in the results if the user has a company assigned to him.
Request example​
{
  "monitoringId": "123456789"
}
Response example​
{
  "monitoringId": "123456789",
  "name": "Carl",
  "surname": "Smith",
  "nationality": "",
  "dob": null,
  "isActive": true,
  "expiration": "2022-02-02",
  "scanRefList": "[]",
  "alert_status": "DECLINED",
  "results": [
    {
      "status": {
        "serviceSuspected": true,
        "serviceUsed": true,
        "serviceFound": true,
        "checkSuccessful": true,
        "overallStatus": "SUSPECTED"
      },
      "serviceName": "PilotApiAmlV2NameCheck",
      "serviceGroupType": "AML",
      "uid": "RHO3XRYH32W4C4OAWEWHGH1TS",
      "errorMessage": null,
      "data": [
        {
          "reason": "",
          "listNumber": "000000",
          "suspicion": "PEPS",
          "isActive": true,
          "checkDate": "2021-02-02 20:02:02",
          "isPerson": true,
          "score": 100,
          "nationality": "",
          "surname": "SURNAME",
          "dob": "1956",
          "lastUpdate": "2018-10-24",
          "name": "NAME",
          "listName": "PEPS",
          "whitelisted": false
        }
      ]
    }
  ]
}


Retrieve Monitored Users List​


get monitored subjects list
Authorization: API key pair

Method: GET

Endpoint: https://ivs.idenfy.com/api/v2/get-aml-users


This will retrieve all monitored subjects.
note
If the alert_status has DECLINED value, that user is not monitored anymore and the data won't be updated further.
Response example​
{
  "users": [
    {
      "id": 5074,
      "created": "2022-12-08 08:05:10",
      "monitoring_id": "09165fef-76cf-11ed-9b45-025ad99a18e7",
      "type": "PERSON",
      "name": "Name  Surname",
      "date_of_birth": null,
      "nationality": "LT",
      "last_check_date": "2023-06-02",
      "is_active": true,
      "expiration_time": "2023-12-08",
      "auto_expiration_extension": false,
      "alert_status": "ACCEPTED",
      "is_suspected": false,
      "whitelisted": false
    }
  ]
}




Deleting an entry​


delete monitoring
Authorization: API key pair

Method: POST

Endpoint: https://ivs.idenfy.com/api/v2/delete-monitoring-user/


permanent
Deleting monitoring will result in deletion of all related data associated with monitoring.
Request example​
{
  "monitoringId": "12345678"
}
A successful API call returns an HTTP response with status 200.




Subscribe/extend monitoring expiration date of a subject​


automatic monitoring extension
Authorization: API key pair

Method: POST

Endpoint: https://ivs.idenfy.com/api/v2/monitoring-subscription


The subject's monitoring date can be automatically extended by setting autoExpirationExtension to true (subscribed), and will continue to extend until either you run out of credits or manually unsubscribe or delete the monitoring subject.
Request example​
{
  "monitoringId": "e1d2a8d5-eb39-11ed-b4c0-0187e22eae15",
  "autoExpirationExtension": true
}