This section provides information how to submit customer details to our database and is focused on individuals requiring risk assessment. It includes examples of API requests with mandatory and optional fields, a comprehensive list of all available fields, common responses and error descriptions.

HTTP Method: POST

Path: {{baseUrl}}/amlyze-ws-rest/customer

ContentType: application/json

Authorization: Bearer Token

API requests examples

Fields

communicationNumber
string
required

Unique number of communication. It is used for risk assessment callback. This field can store up to 256 characters.

Example: Test_ComNr_002mHzZZ

requester
string
required

Name of the system requesting web service.

Example: Amlyze

businessUnit
string from classifier list

❗Mandatory field for clients utilizing a multi-organizational solution. Omit this parameter unless instructed about it.

It serves to specify the unique identifier for the business unit. Business units are logical groupings of users and data. Each business unit can have its own set of users, permissions, and data access rules.

Example: BUSINESS_UNIT_NAME

action
string from enum

Element is used to indicate whether a client needs to be created or the existing customer’s data to be updated. As this field is not mandatory and if not provided, CREATE values is set as default.

❗ By UPDATEing, all data will be replaced with newly received one

Enum class values: CREATE, UPDATE

Example: UPDATE

sourceOfRiskLevel
string
required

The value EVALUATE is used for initiating a customer risk assessment.

Value: EVALUATE

customerStatus
string from enum
required

Customer’s predefined status represents the current standing or state of a customer’s relationship with a business or organization

Enum class values: PENDING, ACTIVE, REJECTED, SUSPENDED, CLOSED

PENDING - Customer application is received but not yet prepared for upcoming workflow

ACTIVE - Customer is onboarded and ready for workflow

REJECTED- the customer for some reasons was rejected before opening an account for him

SUSPENDED - Customer’s activities for some reasons are restricted

CLOSED - Customer’s profile is disabled

Example: ACTIVE

riskManagementCategory
string from classifier list
required

Code of risk management category of the object. Value must be from a classifier list personalized to your company.

Example: IND_AMLYZE

entityType
string
required

Notifies about customer type.

Value: INDIVIDUAL

customerExtId
string
required

Unique external customer identifier. This identifier corresponds to the client’s identifier in the financial institution.

Example: cust_1232

applicationDate
date
required

Date when customer first applied.

Example: 2020-01-03

firstName
string
required

First name of individual entity.

Example: Jose

lastName
string
required

Last name of individual entity.

Example: Rodriguez

citizenshipCountry
string from classifier list
required

Country of citizenship of individual entity.

Example: LT

initializeScreeningProcesses
list[]

Defines which lists to check during screening process. Strings of the list are noted in the dropdown below.

Example: PEP, ADVERSE_MEDIA

birthDate
date

Date of birth of individual entity

Example: 2000-01-01

approvalDate
date

Date of application approval - onboarding date.

Example: 2023-10-01T09:45:00.000+02:00

closingDate
date

❗Mandatory only when customerStatus = CLOSED. Not used when customerStatus is PENDING, ACTIVE, REJECTED or SUSPENDED.

Example: 1995-05-24

birthCountry
string from classifier list

Country of birth of individual entity.

Example: LT

nationalCode
string

National code or national identification number of individual. If a country does not issue national code, any other unique identifier can be used:

  • Passport number
  • Social security number of person
  • A number of taxpayer or registration certificate of the company, etc
  • A number of taxpayer or registration certificate of the company

Example: 50001010022

secondCitizenshipCountry
string from classifier list

Country of second citizenship of individual entity.

Value: LV

permanentResidenceCountry
string from classifier list

Country of permanent residency of an individual entity.

Value: LT

isLegalResident
boolean

Indicator for whether individual entity is a legal resident.

Example: true

isPEP
boolean

Identification for whether a person is politically exposed.

Example: true

isSanctioned
boolean

Identification for whether a person is sanctioned.

Example: false

isInAdverseMedia
boolean

An indication of the existence of information on adverse media about the entity.

Example: true

isInInternalList
boolean

An indication of the existence of information on internal list about the entity.

Example: true

isFamilyPEP
boolean

Identification of whether a family member of an individual entity is politically exposed.

Example: false

isLitigated
boolean

Indicator if the customer is being litigated.

Example: false

amlOfficer
boolean

Indicator for the person being AML officer.

Example: false

listPurpose
string from enum

Indicator whether entity is white/black listed.

Enum class values: WHITE, BLACK

Example: WHITE

fieldOfActivity
object{}

Information about the activities. Fields of the object properties are described in the dropdown below.

isActualAddressDeclared
boolean

Indicator for actual address declaration.

Example: true

isCorrespondenceAddressDeclared
boolean

Indicator for actual address declaration.

Example: false

activityDescription
string

Description of entity activity.

Example: Financial activity

incomeSourceDescription
string

Description of income source of the entity.

Example: Job salary

initialDepositSource
string

Source of initial deposit.

Example: Salary

initialDepositBank
string

Bank of the initial deposit

Example: TBC

initialDepositAccount
string

Account of initial deposit

Example: LT0089500500000070

initialDepositAmount
double

Amount of initial deposit.

Example: 8500.48

initialDepositCurrency
string from classifier list

This currency field notifies about initial deposit currency.

Example: EUR

doesCashDominate
boolean

Indicator for cash being the main income source.

Example: true

listContact
list[]
listAddress
list[]
listBusinessEntityDocument
list[]
listAppealReason
list[]
listIntroductionSource
list[]
listOrderedService
list[]
listDeclaredTurnover
list[]
listIncomeSource
list[]
listPaymentPurpose
list[]
listSourceOfWealth
list[]
listPaymentCountry
list[]
listActivity
list[]
listRegionOfActivity
list[]
listCountryOfActivity
list[]
listCountryOfTaxPayment
list[]
listAdditionalValues
list[]
listRelatedEntity
list[]

List for related business entities. Fields of the list are described in the dropdown below.

List of possible responses

This part lists common responses after the submission of the request.

200 OK
  "resultType": "REQUEST_ACCEPTED"


400 Bad Request
    "resultType": "REQUEST_REJECTED",
    "errorCode": "O001",
    "errorDescription": "CommunicationNumber already used in amlyze"


404 Not Found
    "timestamp": "2024-05-26T16:49:50.237+00:00",
    "status": 404,
    "error": "Not Found",
    "path": "/amlyze-ws-rest/customerr" --> mistake inside the endpoint


500 Internal Server Error
  "resultType": "REQUEST_REJECTED"
  "status": 500,
  "error": "Internal Server Error"

List of possible errors

This section lists the possible errors that can occur when making a bad customer request to the API. A bad request is a request that somehow does not follow the API specifications.

Error Description
ActivityType is mandatory
ActivityType must be defined in Amlyze
AddressType is mandatory.
AddressType is not defined in Amlyze.
Country is mandatory and can’t be empty
Country is mandatory and must exist in Amlyze
AdditionalValue.Code is mandatory
AdditionalValue.Description is mandatory
AdditionalValue.Value is mandatory
AdditionalValue.Datatype is mandatory
Duplicate code in additionalValues
Bad datatype valueCode:
Bad value for valueCode:
Bad value for (format: ‘yyyy-MM-dd’) valueCode:
Bad value for (format: ‘yyyy-MM-dd HH:mm:ss.SSSZ’) valueCode:
Bad value for (values: true false’) valueCode:
EntityType is mandatory. values: INDIVIDUAL, ORGANIZATION
DocumentNumber is mandatory.
DocumentIssueDate is mandatory.
DocumentIssueCountry is mandatory and must exist in Amlyze
DocumentIssueAuthority is mandatory
CustomerExtId is mandatory.
DELETE not yet implemented, contact Amlyze support
Customer already exists
Cannot update not existing customer, use Action = CREATE
Requester is mandatory.
RiskManagementCategory is mandatory.
RiskManagementCategory does not exist in Amlyze
Given RiskManagementCategory not supported for Customer
SourceOfRiskLevel is mandatory. Values: IMPORT, EVALUATE
Cannot demote existing customer to Lead riskManagementCategory
EntityType is mandatory.
When importing, CustomerStatus is mandatory.
When source of risk level IMPORT. ‘Lead’ risk management category is forbidden
When source of risk level IMPORT. RiskLevel is mandatory, values: NONE, LOW, MEDIUM, HIGH, EXTREME
When source of risk level EVALUATE. RiskLevel can’t be provided
ApplicationDate is mandatory
ClosingDate is mandatory for CLOSED CustomerStatus
ClosingDate can not exist for not CLOSED CustomerStatus
Field not allowed for INDIVIDUAL. Field:
For INDIVIDUAL type customer
Field not allowed for ORGANIZATION. Field:
For ORGANIZATION type customer
Problem with field for INDIVIDUAL type customer. CitizenshipCountry not found in amlyze
InitialDepositCurrency not found in amlyze
BirthCountry not defined in Amlyze
CitizenshipCountry not defined in Amlyze
SecondCitizenshipCountry not defined in Amlyze
PermanentResidenceCountry not defined in Amlyze
Problem with field for INDIVIDUAL type customer.
FieldOfActivity.Student.Country is invalid
PensionCountry is invalid
registrationCountry is invalid
registrationCountry must exist in Amlyze
LegalForm must exist in Amlyze
Problem with field for ORGANIZATION type customer.
TurnoverType is mandatory
TurnoverType must exist in amlyze
At least one value must be specified (FROM, TO)
Problem with DeclaredTurnover (index: ).
PaymentPurposeType does not exist in Amlyze
TurnoverDirection is invalid
Problem with PaymentPurpose (index: ).
ServiceType not found in Amlyze
Problem with OrderedService (index: ).
Problem with Customer Contact index = .
Problem with Customer BusinessEntityDocument index = .
Problem with relatedEntity (index: ).
Problem with relatedEntities.
Problem with Address (index: ).
screening process is undefined:
PaymentCountry can’t be empty
PaymentCountry not found in Amlyze
TurnoverDirection is invalid
Problem with PaymentCountry (index: ).
IntroductionSource not found in amlyze
Problem with IntroductionSource (index: ).
Problem with IncomeSource (index: ).
AppealReasonType is mandatory and can’t be empty
AppealReasonType is mandatory and must be defined in Amlyze
Problem with ListAppealReason (index: ).
Problem with activity (index: ).
Problem with RegionOfActivity (index: ).
CountryOfTaxPayment can’t be empty
CountryOfTaxPayment not found in Amlyze
CountryOfTaxPayment (index: ).
Problem with CountryOfActivity (index: ).
Title is mandatory
RegistrationCountry is mandatory
LegalForm is mandatory
FirstName is mandatory
LastName is mandatory
Bad value for TIMESTAMP (format: ‘yyyy-MM-dd HH:mm:ss.SSSZ’) valueCode: lastonlinesupport
Field not allowed for INDIVIDUAL. Field: CompanyAssetValue
Problem with field for INDIVIDUAL type customer. CitizenshipCountry not found in amlyze
When source of risk level IMPORT. ‘Lead’ risk management category is forbidden
Field not allowed for ORGANIZATION. Field: LastName
Screening process is undefined: NOT_EXISTS
Problem with Address (index: 0 ). Country is mandatory and must exist in Amlyze
Field not allowed for ORGANIZATION. Field: SecondCitizenshipCountry
Problem with field for ORGANIZATION type customer. Problem with relatedEntity (index: 0 ). Relation type is mandatory
Problem with PaymentCountry (index: 0 ). PaymentCountry not found in Amlyze
Field not allowed for INDIVIDUAL. Field: NumberOfEmployees
Bad value for BOOLEAN (values: true false’) valueCode: isvip
ApplicationDate is mandatory
CustomerExtId is mandatory
Problem with Customer BusinessEntityDocument index = 0 . DocumentIssueCountry is mandatory and must exist in Amlyze
CountryOfTaxPayment (index: 0 ). CountryOfTaxPayment not found in Amlyze
RiskManagementCategory does not exist in Amlyze
Field not allowed for INDIVIDUAL. Field: LicenseDescription
Field not allowed for INDIVIDUAL. Field: NumberOfAudits
Field not allowed for ORGANIZATION. Field: FirstName
CountryOfTaxPayment (index: 0 ). CountryOfTaxPayment not found in Amlyze
PermanentResidenceCountry not defined in Amlyze
PensionCountry is invalid
Field not allowed for INDIVIDUAL. Field: RegionOfActivityDescription
BirthCountry not defined in Amlyze
ClosingDate can not exist for not CLOSED CustomerStatus
ClosingDate is mandatory for CLOSED CustomerStatus
Problem with field for ORGANIZATION type customer. Problem with relatedEntity (index: 0 ). Problem with BusinessEntityDocuments (index: 0 ). EntityType is mandatory. values : INDIVIDUAL, ORGANIZATION
Problem with field for ORGANIZATION type customer. Problem with relatedEntity (index: 0 ). Problem with Contact (index: 0 ). ContactDetails is mandatory
Field not allowed for INDIVIDUAL. Field: Title
Bad value for INTEGER valueCode: number_users
For ORGANIZATION type customer Title is mandatory
EntityType is mandatory
Field not allowed for ORGANIZATION. Field: PermanentResidenceCountry
Field not allowed for INDIVIDUAL. Field: LegalForm
Field not allowed for INDIVIDUAL. Field: ThirdPartyServicesUsedDescription
Field not allowed for ORGANIZATION. Field: BirthCountry
Field not allowed for INDIVIDUAL. Field: GIIN
Problem with field for ORGANIZATION type customer. Problem with relatedEntity (index: 0 ). Relation type is not defined in Amlyze
Cannot update not existing customer, use Action = CREATE
Problem with field for ORGANIZATION type customer. Problem with relatedEntity (index: 0 ). Country not defined in Amlyze
Problem with field for ORGANIZATION type customer. Problem with relatedEntity (index: 0 ). EntityType is mandatory
RegistrationCountry must exist in Amlyze
Problem with field for ORGANIZATION type customer. Problem with relatedEntity (index: 0 ). Problem with Contact (index: 0 ). ContactType is mandatory. values: MOBILEPHONE, FIXEDPHONE, EMAIL, WEBSITE
Field not allowed for INDIVIDUAL. Field: EstablishmentDate
Field not allowed for INDIVIDUAL. Field: PeriodsOfAuditsInYears
Problem with field for ORGANIZATION type customer. Problem with relatedEntity (index: 1 ). bad value for BOOLEAN (values: true false’) valueCode: is_related_to_Lithuania
Field not allowed for INDIVIDUAL. Field: OrganizationalStructureDescription
RiskManagementCategory is mandatory
Problem with field for ORGANIZATION type customer.