Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 24 Next »

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

name

string

YES

The name of the person.

dateOfBirth

string

NO

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

gender

string

NO

Gender of the person.

referenceId

string

NO

A unique identifier for the person’es reference in the system.

referenceType

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

id

string

The recordId of the person for subsequent calls.


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

naturalEntityRecords

array<object>

-

An array of objects representing the person records.

naturalEntityRecords.name

string

YES

The name of the person.

naturalEntityRecords.dateOfBirth

string

NO

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

naturalEntityRecords.gender

string

NO

Gender of the person.

naturalEntityRecords.referenceId

string

NO

A unique identifier for the person’es reference in the system.

naturalEntityRecords.referenceType

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

hasErrors

boolean

A boolean value indicating whether there are any errors in the response. If there are errors, the records array may contain error objects.

records

array

An array of objects representing the records in the response.

records.id

string

The unique identifier for the record in the system.

records.createdAt

string

The date and time when the record was created in ISO 8601 format.

records.name

string

The name of the person.

records.dateOfBirth

string

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

records.gender

string

Gender of the person.

records.referenceId

string

A unique identifier for the person’es reference in the system.

records.referenceType

string

User created reference for the person in the system, for example "My Reference".

records.error

object

An optional object containing information about any errors associated with the record.

records.error.code

string

A string code identifying the type of error that occurred.

records.error.message

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

naturalEntityRecords

array<object>

-

An array of objects representing id’s of person records.

naturalEntityRecords.id

string

The recordId of the person to be removed.


🥫 Response

After successfully deleting person records from monitoring, you’ll get a response with success code 200: Success with fields:

Field

Type

Description

hasErrors

boolean

A boolean value indicating whether there are any errors in the response. If there are errors, the records array may contain error objects.

deletedRecords

array

An array of objects representing the records in the response.

deletedRecords.id

string

The recordId of the removed person.

deletedRecords.error

object

An optional object containing information about any errors associated with the record.

deletedRecords.error.code

string

A string code identifying the type of error that occurred.

deletedRecords.error.message

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

name

string

YES

The updated name of the person.

records.dateOfBirth

string

NO

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

records.gender

string

NO

Gender of the person.

referenceId

string

NO

An updated identifier for the person’es reference in the system.

referenceType

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

naturalEntityRecords

array<object>

-

An array of objects representing the person records.

naturalEntityRecords.name

string

YES

The updated name of the person.

naturalEntityRecords.dateOfBirth

string

NO

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

naturalEntityRecords.gender

string

NO

Gender of the person.

naturalEntityRecords.referenceId

string

NO

An updated identifier for the person’es reference in the system.

naturalEntityRecords.referenceType

string

NO

Updated reference for the person in the system.

naturalEntityRecords.id

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

hasErrors

boolean

A boolean value indicating whether there are any errors in the response. If there are errors, the records array may contain error objects.

records

array

An array of objects representing the records in the response.

records.id

string

The unique identifier for the record in the system.

records.createdAt

string

The date and time when the record was created in ISO 8601 format.

records.name

string

The name of the person.

records.dateOfBirth

string

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

records.gender

string

Gender of the person.

records.referenceId

string

A unique identifier for the person’es reference in the system.

records.referenceType

string

User created reference for the person in the system, for example "My Reference".

records.error

object

An optional object containing information about any errors associated with the record.

records.error.code

string

A string code identifying the type of error that occurred.

records.error.message

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

id

string

The unique identifier for the record in the system.

createdAt

string

Date and time when the response was created.

name

string

The name of the person associated with the response.

dateOfBirth

string

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

gender

string

Gender of the person.

referenceId

string

A unique identifier for the person’es reference in the system.

referenceType

string

User created reference for the person in the system, for example "My Reference".

openCount

integer

The number of open matches for the monitor record

falsePositiveCount

integer

The number of matches already closed as false positive

truePositiveCount

integer

The number of matches already closed as true positive.

discardedCount

integer

The number of matches already discarded.

createdDateTimeIso

string

Date and time when the person record was first created.

lastUpdatedDateTimeIso

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

id

string

NO

The unique identifier for the record in the system.

dateOfBirth

string

NO

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

gender

string

NO

Gender of the person.

name

string

NO

The name of the person.

referenceId

string

NO

A unique identifier for the person’es reference in the system.

referenceType

string

NO

User created reference for the person in the system, for example "My Reference".

from

string

NO

Date FROM when person record was added to worklist.

Response will return person records added after this date.

to

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

hasErrors

boolean

A boolean value indicating whether there are any errors in the response. If there are errors, the records array may contain error objects.

records

array

An array of objects representing the records in the response.

records.id

string

The unique identifier for the record in the system.

records.createdAt

string

The date and time when the record was created in ISO 8601 format.

records.name

string

The name of the person.

records.dateOfBirth

string

Date of birth of the person.

Format: YYYY-MM-DD or YYYY.

records.gender

string

Gender of the person.

records.referenceId

string

A unique identifier for the person’es reference in the system.

records.referenceType

string

User created reference for the person in the system, for example "My Reference".

records.error

object

An optional object containing information about any errors associated with the record.

records.error.code

string

A string code identifying the type of error that occurred.

records.error.message

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

totalCount

integer

Total number of matches.

matches

array<object>

An array of objects representing the match information.

matches.currentStatus

string

Current status of the person match.

Possible enum values:

  • Open - match requires review.

  • TruePositive - match closed as true positive

  • FalsePositive - match closed as false positive

  • Discarded - match was discarded

matches.matchId

string

The unique Id of the person match.

matches.version

integer

Can be used to detect when the profile has changed.

matches.resourceId

string

The unique id that can be used to retrieve the detailed information about person profile via GET /v1/natural-entity-details/{resourceId} endpoint.

matches.score

integer

The match score. This means how accurate the found person match the monitored person.

E.g. "score": 100 means that the found person is the exact match to the provided in the monitoring.

Possible values from 75 to 100

matches.match

string

The person name that has been matched in the monitoring.

matches.name

string

The name of the found person.

matches.countries

string

The list of countries from the addresses and nationalities of the profile.

matches.datesOfBirth

array<string>

An array of strings representing the person dates of birth.

Format: YYYY-MM-DD or YYYY.

matches.gender

string

Gender of the person.

matches.profileImage

string

The URL to person’s profile image.

matches.dataSets

string

Active datasets where person is tagged in.

Possible enum values are any of the described datasets here.

matches.matchVersion

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

currentStatus

string

Current status of the person match.

Possible enum values:

  • Open - match requires review.

  • TruePositive - match closed as true positive

  • FalsePositive - match closed as false positive

  • Discarded - match was discarded

matchId

string

The unique Id of the person match.

version

string

Can be used to detect when the profile has changed.

resourceId

string

The unique id that can be used to retrieve the detailed information about person profile via GET /v1/natural-entity-details/{resourceId} endpoint.

score

string

The match score. This means how accurate the found person match the monitored person.

E.g. "score": 100 means that the found person is the exact match to the provided in the monitoring.

Possible values from 75 to 100

match

integer

The person name that has been matched in the monitoring.

name

integer

The name of the found person.

countries

integer

The list of countries from the addresses and nationalities of the profile.

datesOfBirth

array<string>

An array of strings representing the person dates of birth.

Format: YYYY-MM-DD or YYYY.

gender

string

Gender of the person.

profileImage

string

The URL to person’s profile image.

dataSets

integer

Active datasets where person is tagged in.

Possible enum values are any of the described datasets here.

matchVersion

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.



🗂️ Code Examples

1️⃣ Start monitoring a person

🗒️ Example request

 Expand to see the example request
{
  "name": "Boyko Borissov",
  "dateOfBirth": "1994-08-22",
  "gender": "Male",
  "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
  "referenceType": "My Reference"
}

🗒️ Example response

 Expand to see the example response
{
  "id": "54d0e87303644a599651f7d0bab9e952"
}

2️⃣ Bulk add multiple persons to the monitoring

🗒️ Example request

 Expand to see the example request
{
  "naturalEntityRecords": [
    {
      "name": "Boyko Borissov",
      "dateOfBirth": "1994-08-22",
      "gender": "Male",
      "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
      "referenceType": "My Reference"
    }
  ]
}

🗒️ Example response

 Expand to see the example response
{
  "hasErrors": false,
  "records": [
    {
      "id": "b078226e94d844c99a681dad7f61dce8",
      "createdAt": "2023-03-20T12:02:24.395Z",
      "name": "Boyko Borissov",
      "dateOfBirth": "1994-08-22",
      "gender": "Male",
      "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
      "referenceType": "My Reference",
      "error": {
        "code": "MS101",
        "message": "Error message"
      }
    }
  ]
}

3️⃣ Bulk remove persons from monitoring

🗒️ Example request

 Expand to see the example request
{
  "naturalEntityRecords": [
    {
      "id": "b078226e94d844c99a681dad7f61dce8"
    }
  ]
}

🗒️ Example response

 Expand to see the example response
{
  "hasErrors": true,
  "deletedRecords": [
    {
      "id": "b078226e94d844c99a681dad7f61dce8",
      "error": {
        "code": "MS101",
        "message": "Error message"
      }
    }
  ]
}

4️⃣ Update person monitoring record

🗒️ Example request

 Expand to see the example request
{
  "name": "Boyko Borissov",
  "dateOfBirth": "1994-08-22",
  "gender": "Male",
  "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
  "referenceType": "My Reference"
}

5️⃣ Bulk update person monitoring records

🗒️ Example request

 Expand to see the example request
{
  "naturalEntityRecords": [
    {
      "name": "Boyko Borissov",
      "dateOfBirth": "1994-08-22",
      "gender": "Male",
      "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
      "referenceType": "My Reference",
      "id": "b078226e94d844c99a681dad7f61dce8"
    }
  ]
}

🗒️ Example response

 Expand to see the example response
{
  "hasErrors": false,
  "records": [
    {
      "id": "b078226e94d844c99a681dad7f61dce8",
      "createdAt": "2023-03-20T12:03:20.891Z",
      "name": "Boyko Borissov",
      "dateOfBirth": "1994-08-22",
      "gender": "Male",
      "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
      "referenceType": "My Reference",
      "error": {
        "code": "MS101",
        "message": "Error message"
      }
    }
  ]
}

6️⃣ Retrieve a specific person monitoring record

🗒️ Example response

 Expand to see the example response
{
  "id": "b078226e94d844c99a681dad7f61dce8",
  "createdAt": "2023-03-20T12:03:45.415Z",
  "name": "Boyko Borissov",
  "dateOfBirth": "1994-08-22",
  "gender": "Male",
  "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
  "referenceType": "My Reference",
  "openCount": 0,
  "falsePositiveCount": 0,
  "truePositiveCount": 0,
  "discardedCount": 0,
  "createdDateTimeIso": "2021-10-05T10:10:08.270Z",
  "lastUpdatedDateTimeIso": "2021-10-05T10:10:08.270Z"
}

7️⃣ Retrieve all person monitoring records

🗒️ Example request

 Expand to see the example request
{
  "id": "b078226e94d844c99a681dad7f61dce8",
  "dateOfBirth": "1994-08-22",
  "gender": "Male",
  "name": "Boyko Borissov",
  "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
  "referenceType": "My Reference",
  "from": "2023-01-01",
  "to": "2023-12-31"
}

🗒️ Example response

 Expand to see the example response
{
  "hasErrors": false,
  "records": [
    {
      "id": "b078226e94d844c99a681dad7f61dce8",
      "createdAt": "2023-03-20T12:03:59.360Z",
      "name": "Boyko Borissov",
      "dateOfBirth": "1994-08-22",
      "gender": "Male",
      "referenceId": "02241D31-2058-45AD-8D03-6AACF97863B8",
      "referenceType": "My Reference",
      "error": {
        "code": "MS101",
        "message": "Error message"
      }
    }
  ]
}

8️⃣ Retrieve all matches of the person

🗒️ Example response

 Expand to see the example response
{
  "totalCount": 15,
  "matches": [
    {
      "currentStatus": "Open",
      "matchId": "432523",
      "version": 15346444345,
      "resourceId": "1f5a940e6a16d390bfe75055c3176f64c5b397880ff08e04b61ad7325af76cc4",
      "score": 100,
      "match": "Boyko Borissov",
      "name": "Boyko Metodiev Borisov",
      "countries": [
        "US"
      ],
      "datesOfBirth": [
        "1994",
        "1994-08-22"
      ],
      "gender": "Male",
      "profileImage": "https://www.acurisriskintelligence.com/cdn/content/0024300000/0024297990.jpg",
      "dataSets": [
        "ExternalPepCurrent",
        "ExternalSanctionsCurrent"
      ],
      "matchVersion": 1
    }
  ]
}

9️⃣ Retrieve a specific match of the person

🗒️ Example response

 Expand to see the example response
{
  "currentStatus": "Open",
  "matchId": "432523",
  "version": 15346444345,
  "resourceId": "1f5a940e6a16d390bfe75055c3176f64c5b397880ff08e04b61ad7325af76cc4",
  "score": 100,
  "match": "Boyko Borissov",
  "name": "Boyko Metodiev Borisov",
  "countries": [
    "US"
  ],
  "datesOfBirth": [
    "1994",
    "1994-08-22"
  ],
  "gender": "Male",
  "profileImage": "https://www.acurisriskintelligence.com/cdn/content/0024300000/0024297990.jpg",
  "dataSets": [
    "ExternalPepCurrent",
    "ExternalSanctionsCurrent"
  ],
  "matchVersion": 1
}

🔟 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


  • No labels

0 Comments

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account.