Table of Contents
ℹ️ Introduction
Once monitoring rules in the worklist are set up, you can do the following actions with persons:
Manage person records:
Add a person to monitoring
Remove person from monitoring
Update person record
Get person records
Retrieve person matches
Get monitored person’s details
⚙️ Manage Person Records
1️⃣ Start monitoring a person
To start monitoring a person, add it to the monitoring worklist.
To do this, call the following endpoint:
POST /v1/worklists/{worklistId}/natural-entity-records
This endpoint only capable to add 1 person at a time. To add multiple persons in one request, please check out the next section.
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🎯 Request body
Field | Type | Required | Description |
---|---|---|---|
| string | YES | The name of the person. |
| string | NO | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
| string | NO | Gender of the person. |
| string | NO | A unique identifier for the person’es reference in the system. |
| string | NO | User created reference for the person in the system, for example "My Reference". |
🥫 Response
After successfully creating a person record you’ll get a response with success code 201: Created
and recordId
of the person for subsequent calls.
Field | Type | Description |
---|---|---|
| string | The |
2️⃣ Bulk add persons to the monitoring
You can add multiple persons to the monitoring with one call.
To do this, call the following endpoint:
POST /v1/worklists/{worklistId}/natural-entity-records/batch
This endpoint capable to add up to 25 records with one call.
POST /v1/worklists/{worklistId}/natural-entity-records/batch-async
This endpoint capable to add up to 10.000 records with one call. Records added through this endpoint will take longer to be processed and appear in the worklist.
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🎯 Request body
Field | Type | Required | Description |
---|---|---|---|
| array<object> | - | An array of objects representing the person records. |
naturalEntityRecords. | string | YES | The name of the person. |
naturalEntityRecords. | string | NO | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
naturalEntityRecords. | string | NO | Gender of the person. |
naturalEntityRecords. | string | NO | A unique identifier for the person’es reference in the system. |
naturalEntityRecords. | string | NO | User created reference for the person in the system, for example "My Reference". |
🥫 Response
After successfully creating a person records you’ll get a response with success code 200: Success
with fields:
Field | Type | Description |
---|---|---|
| boolean | A boolean value indicating whether there are any errors in the response. If there are errors, the records array may contain error objects. |
| array | An array of objects representing the records in the response. |
records. | string | The unique identifier for the record in the system. |
records. | string | The date and time when the record was created in ISO 8601 format. |
records. | string | The name of the person. |
records. | string | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
records. | string | Gender of the person. |
records. | string | A unique identifier for the person’es reference in the system. |
records. | string | User created reference for the person in the system, for example "My Reference". |
records. | object | An optional object containing information about any errors associated with the record. |
records.error. | string | A string code identifying the type of error that occurred. |
records.error. | string | A human-readable message describing the error that occurred. |
3️⃣ Stop monitoring a person
To stop monitoring the person, remove it from the monitoring worklist.
To do this, call the following endpoint:
DELETE /v1/worklists/{worklistId}/natural-entity-records/{recordId}
This endpoint only capable to remove 1 person at a time. To remove multiple persons in one request, please check out the section below.
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
recordId | string | YES | The unique Id of the person to update. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🥫 Response
After successfully deleting the person record from monitoring, you’ll get a response with success code 204: No Content
.
4️⃣ Bulk remove persons from monitoring
You can remove multiple persons from the monitoring with one call.
To do this, call the following endpoint:
DELETE /v1/worklists/{worklistId}/natural-entity-records/batch
This endpoint capable to remove up to 25 records with one call.
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🎯 Request body
Field | Type | Required | Description |
---|---|---|---|
| array<object> | - | An array of objects representing id’s of person records. |
naturalEntityRecords. | string | The |
🥫 Response
After successfully deleting person records from monitoring, you’ll get a response with success code 200: Success
with fields:
Field | Type | Description |
---|---|---|
| boolean | A boolean value indicating whether there are any errors in the response. If there are errors, the records array may contain error objects. |
| array | An array of objects representing the records in the response. |
deletedRecords. | string | The |
deletedRecords. | object | An optional object containing information about any errors associated with the record. |
deletedRecords.error. | string | A string code identifying the type of error that occurred. |
deletedRecords.error. | string | A human-readable message describing the error that occurred. |
5️⃣ Update person monitoring record
You can update existing person record.
To do this, call the following endpoint:
PUT /v1/worklists/{worklistId}/natural-entity-records/{recordId}
This endpoint only capable to update 1 person at a time. To update multiple persons in one request, please see the next section.
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
recordId | string | YES | The unique Id of the person to update. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🎯 Request body
Field | Type | Required | Description |
---|---|---|---|
| string | YES | The updated name of the person. |
records. | string | NO | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
records. | string | NO | Gender of the person. |
| string | NO | An updated identifier for the person’es reference in the system. |
| string | NO | An updated reference for the person in the system. |
🥫 Response
After successfully updating a person record, you’ll get a response with success code 204: No Content
.
6️⃣ Bulk update person monitoring records
You can update multiple persons with one call.
To do this, call the following endpoint:
PUT /v1/worklists/{worklistId}/natural-entity-records/batch
This endpoint capable to update up to 25 records with one call.
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🎯 Request body
Field | Type | Required | Description |
---|---|---|---|
| array<object> | - | An array of objects representing the person records. |
naturalEntityRecords. | string | YES | The updated name of the person. |
naturalEntityRecords. | string | NO | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
naturalEntityRecords. | string | NO | Gender of the person. |
naturalEntityRecords. | string | NO | An updated identifier for the person’es reference in the system. |
naturalEntityRecords. | string | NO | Updated reference for the person in the system. |
naturalEntityRecords. | string | YES | The unique Id of the person which will be updated. |
🥫 Response
After successfully updating person records, you’ll get a response with success code 200: Success
with fields:
Field | Type | Description |
---|---|---|
| boolean | A boolean value indicating whether there are any errors in the response. If there are errors, the records array may contain error objects. |
| array | An array of objects representing the records in the response. |
records. | string | The unique identifier for the record in the system. |
records. | string | The date and time when the record was created in ISO 8601 format. |
records. | string | The name of the person. |
records. | string | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
records. | string | Gender of the person. |
records. | string | A unique identifier for the person’es reference in the system. |
records. | string | User created reference for the person in the system, for example "My Reference". |
records. | object | An optional object containing information about any errors associated with the record. |
records.error. | string | A string code identifying the type of error that occurred. |
records.error. | string | A human-readable message describing the error that occurred. |
7️⃣ Retrieve a specific person monitoring record
You can retrieve information about a specific person record.
To do this, call the following endpoint:
GET /v1/worklists/{worklistId}/natural-entity-records/{recordId}
This endpoint only capable to retrieve 1 person at a time. To retrive multiple persons in one request, please see the next section.
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
recordId | string | YES | The unique Id of the person to retrieve. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🥫 Response
After successfully retrieving a person record you’ll get a response with success code 200: Success
with fields:
Field | Type | Description |
---|---|---|
| string | The unique identifier for the record in the system. |
| string | Date and time when the response was created. |
| string | The name of the person associated with the response. |
| string | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
| string | Gender of the person. |
| string | A unique identifier for the person’es reference in the system. |
| string | User created reference for the person in the system, for example "My Reference". |
| integer | The number of open matches for the monitor record |
| integer | The number of matches already closed as false positive |
| integer | The number of matches already closed as true positive. |
| integer | The number of matches already discarded. |
| string | Date and time when the person record was first created. |
| string | Date and time when the person record was last updated. |
8️⃣ Retrieve all person monitoring records
You can retrieve information about all person records in the worklist.
To do this, call the following endpoint:
POST /v1/worklists/{worklistId}/natural-entity-records/search
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🎯 Request body
All request fields are optional. They can be passed to narrow the search.
Field | Type | Required | Description |
---|---|---|---|
| string | NO | The unique identifier for the record in the system. |
| string | NO | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
| string | NO | Gender of the person. |
| string | NO | The name of the person. |
| string | NO | A unique identifier for the person’es reference in the system. |
| string | NO | User created reference for the person in the system, for example "My Reference". |
| string | NO | Date FROM when person record was added to worklist. Response will return person records added after this date. |
| string | NO | Date TO when person record was added to worklist. Response will return person records added before this date. |
🥫 Response
After successfully retrieving a person records, you’ll get a response with success code 200: Success
with fields:
Field | Type | Description |
---|---|---|
| boolean | A boolean value indicating whether there are any errors in the response. If there are errors, the records array may contain error objects. |
| array | An array of objects representing the records in the response. |
records. | string | The unique identifier for the record in the system. |
records. | string | The date and time when the record was created in ISO 8601 format. |
records. | string | The name of the person. |
records. | string | Date of birth of the person. Format: YYYY-MM-DD or YYYY. |
records. | string | Gender of the person. |
records. | string | A unique identifier for the person’es reference in the system. |
records. | string | User created reference for the person in the system, for example "My Reference". |
records. | object | An optional object containing information about any errors associated with the record. |
records.error. | string | A string code identifying the type of error that occurred. |
records.error. | string | A human-readable message describing the error that occurred. |
🛒 Retrieve Person Matches
If any of your monitored person records gets a match in our AML datasets, you can retrieve it.
1️⃣ Retrieve all matches of the person
You can retrieve all matches of the person.
To do this, call the following endpoint:
POST /v1/worklists/{worklistId}/natural-entity-records/{recordId}/search
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
recordId | string | YES | The unique Id of the person record to retrieve. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🥫 Response
After successfully retrieving the person matches you’ll get a response with success code 201: Created
with fields:
Field | Type | Description |
---|---|---|
| integer | Total number of matches. |
| array<object> | An array of objects representing the match information. |
matches. | string | Current status of the person match. Possible enum values:
|
matches. | string | The unique Id of the person match. |
matches. | integer | Can be used to detect when the profile has changed. |
matches. | string | The unique id that can be used to retrieve the detailed information about person profile via |
matches. | integer | The match score. This means how accurate the found person match the monitored person. E.g. Possible values from |
matches. | string | The person name that has been matched in the monitoring. |
matches. | string | The name of the found person. |
matches. | string | The list of countries from the addresses and nationalities of the profile. |
matches. | array<string> | An array of strings representing the person dates of birth. Format: YYYY-MM-DD or YYYY. |
matches. | string | Gender of the person. |
matches. | string | The URL to person’s profile image. |
matches. | string | Active datasets where person is tagged in. Possible enum values are any of the described datasets here. |
matches. | integer | This value can be used for version control. |
2️⃣ Retrieve a specific match of the person
You can retrieve a specific person’es match.
To do this, call the following endpoint:
GET /v1/worklists/{worklistId}/natural-entity-records/{recordId}/matches/{matchId}
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
worklistId | string | YES | The unique Id of the worklist. |
recordId | string | YES | The unique Id of the person record to retrieve. |
matchId | string | YES | The unique Id of the person match to retrieve. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🥫 Response
After successfully retrieving a person match you’ll get a response with success code 200: Success
with fields:
Field | Type | Description |
---|---|---|
| string | Current status of the person match. Possible enum values:
|
| string | The unique Id of the person match. |
| string | Can be used to detect when the profile has changed. |
| string | The unique id that can be used to retrieve the detailed information about person profile via |
| string | The match score. This means how accurate the found person match the monitored person. E.g. Possible values from |
| integer | The person name that has been matched in the monitoring. |
| integer | The name of the found person. |
| integer | The list of countries from the addresses and nationalities of the profile. |
| array<string> | An array of strings representing the person dates of birth. Format: YYYY-MM-DD or YYYY. |
| string | Gender of the person. |
| string | The URL to person’s profile image. |
| integer | Active datasets where person is tagged in. Possible enum values are any of the described datasets here. |
| string | This value can be used for version control. |
📥 Get Monitored Person Match Details
After retrieving the person match, you can get detailed information about a matched person.
To do this, call the following endpoint:
GET /v1/natural-entity-details/{resourceId}
🔠 Headers
Parameter | Type | Required | Description |
---|---|---|---|
resourceId | string | YES | The unique Id of the matched person profile to retrieve the detailed information. |
Correlation-Id | string | NO | A unique identifier assigned to the request. |
Application-Id | string | NO | Your application Id. Please contact support@ondato.com you don’t have one. |
Access token | string | YES | Described in the Authentication part |
🥫 Response
After successfully retrieving details of the matched person profile, you’ll get a response with success code 200: Success
and the response.
The response structure is the same as for our AML Screening response. You can check it out here: https://ondato.atlassian.net/wiki/spaces/PUB/pages/2379612161/Person+AML+Screening#%F0%9F%93%87-Get-person-details-by-id
🗂️ Code Examples
1️⃣ Start monitoring a person
🗒️ Example request
🗒️ Example response
2️⃣ Bulk add multiple persons to the monitoring
🗒️ Example request
🗒️ Example response
3️⃣ Bulk remove persons from monitoring
🗒️ Example request
🗒️ Example response
4️⃣ Update person monitoring record
🗒️ Example request
5️⃣ Bulk update person monitoring records
🗒️ Example request
🗒️ Example response
6️⃣ Retrieve a specific person monitoring record
🗒️ Example response
7️⃣ Retrieve all person monitoring records
🗒️ Example request
🗒️ Example response
8️⃣ Retrieve all matches of the person
🗒️ Example response
9️⃣ Retrieve a specific match of the person
🗒️ Example response
🔟 Get monitored person match details
Example can be found here: https://ondato.atlassian.net/wiki/spaces/PUB/pages/2379612161/Person+AML+Screening#%3Ainfo%3A-%F0%9F%A7%91%E2%80%8D%F0%9F%A6%B1-Get-person-details-by-id
Add Comment