# Account import Source: https://api.amlyze.com/api-reference/account/account-import /api/openapi_api_adapter.json post /amlyze-ws-rest/account This section provides information how to submit account details to our database. # Batch import of account balances Source: https://api.amlyze.com/api-reference/account/batch-import-of-account-balances /api/openapi_api_adapter.json post /amlyze-ws-rest/batch-account-balances # Batch import of accounts Source: https://api.amlyze.com/api-reference/account/batch-import-of-accounts /api/openapi_api_adapter.json post /amlyze-ws-rest/batch-accounts Batch data import involve processing large volumes of account data at once. # Update account balance Source: https://api.amlyze.com/api-reference/account/update-account-balance /api/openapi_api_adapter.json put /amlyze-ws-rest/account-balance This section provides detailed information on the endpoints that can be used to create and manage account balances. # Validate batch of accounts without saving Source: https://api.amlyze.com/api-reference/account/validate-batch-of-accounts-without-saving /api/openapi_api_adapter.json post /amlyze-ws-rest/validate-batch-accounts This method sends data only for validating JSON. # Account Type Source: https://api.amlyze.com/api-reference/classifiers/account-type /api/openapi_classifiers.json get /classifier/accountType # Activity Type Source: https://api.amlyze.com/api-reference/classifiers/activity-type /api/openapi_classifiers.json get /classifier/activityType # Address Type Source: https://api.amlyze.com/api-reference/classifiers/address-type /api/openapi_classifiers.json get /classifier/addressType # Appeal Reason Type Source: https://api.amlyze.com/api-reference/classifiers/appeal-reason-type /api/openapi_classifiers.json get /classifier/appealReasonType # Business Unit Source: https://api.amlyze.com/api-reference/classifiers/business-unit /api/openapi_classifiers.json get /classifier/businessUnit # Card Operation SubType Source: https://api.amlyze.com/api-reference/classifiers/card-operation-subtype /api/openapi_classifiers.json get /classifier/cardOperationSubType # Country Source: https://api.amlyze.com/api-reference/classifiers/country /api/openapi_classifiers.json get /classifier/country # Currency Source: https://api.amlyze.com/api-reference/classifiers/currency /api/openapi_classifiers.json get /classifier/currency # Decision Ground Source: https://api.amlyze.com/api-reference/classifiers/decision-ground /api/openapi_classifiers.json get /classifier/decisionGround # Income Source Type Source: https://api.amlyze.com/api-reference/classifiers/income-source-type /api/openapi_classifiers.json get /classifier/incomeSourceType # Introduction Source Type Source: https://api.amlyze.com/api-reference/classifiers/introduction-source-type /api/openapi_classifiers.json get /classifier/introductionSourceType # Legal Form Source: https://api.amlyze.com/api-reference/classifiers/legal-form /api/openapi_classifiers.json get /classifier/legalForm # Operation Type Source: https://api.amlyze.com/api-reference/classifiers/operation-type /api/openapi_classifiers.json get /classifier/operationType # Payment Purpose Type Source: https://api.amlyze.com/api-reference/classifiers/payment-purpose-type /api/openapi_classifiers.json get /classifier/paymentPurposeType # Relation Type Source: https://api.amlyze.com/api-reference/classifiers/relation-type /api/openapi_classifiers.json get /classifier/relationType # Risk Management Category Source: https://api.amlyze.com/api-reference/classifiers/risk-management-category /api/openapi_classifiers.json get /classifier/riskManagementCategory # Service Type Source: https://api.amlyze.com/api-reference/classifiers/service-type /api/openapi_classifiers.json get /classifier/serviceType # Source Of Wealth Source: https://api.amlyze.com/api-reference/classifiers/source-of-wealth /api/openapi_classifiers.json get /classifier/sourceOfWealth # Turnover Type Source: https://api.amlyze.com/api-reference/classifiers/turnover-type /api/openapi_classifiers.json get /classifier/turnoverType # Communication Events by Communication Number Source: https://api.amlyze.com/api-reference/communication-events/communication-events-by-communication-number /api/openapi_api_adapter.json get /api/integration-services/v1/communications-events/{communicationNumber} Retrieves communication events by communication number. This can be used as fallback approach to get information about request. However keep in mind that not all request triggers webhook sending and not all webhooks that are sent have communication number. # Contract registration Source: https://api.amlyze.com/api-reference/contract/contract-registration /api/openapi_api_adapter.json post /amlyze-ws-rest/contract This section provides detailed information on the endpoints that can be used to create and manage contracts. Contracts can be any type of documents with custom set of fields/elements. # Update contract Source: https://api.amlyze.com/api-reference/contract/update-contract /api/openapi_api_adapter.json put /amlyze-ws-rest/contract # Validate a batch of contracts without saving Source: https://api.amlyze.com/api-reference/contract/validate-a-batch-of-contracts-without-saving /api/openapi_api_adapter.json post /amlyze-ws-rest/validate-batch-contracts This method sends data only for validating JSON. # Validate and save a batch of contracts Source: https://api.amlyze.com/api-reference/contract/validate-and-save-a-batch-of-contracts /api/openapi_api_adapter.json post /amlyze-ws-rest/batch-contracts This method sends data and imports contracts in AMLYZE. # Customer kyc scoring completed Source: https://api.amlyze.com/api-reference/customer-assessment/customer-kyc-scoring-completed /webhooks/openapi_webhooks.json webhook app.amlyze.customer.riskmanagement.kyc_scoring.completed Fired when on completion by a human decision/automatically resolution. # Customer kyc scoring pending Source: https://api.amlyze.com/api-reference/customer-assessment/customer-kyc-scoring-pending /webhooks/openapi_webhooks.json webhook app.amlyze.customer.riskmanagement.kyc_scoring.pending Fired when a customer KYC score is pending and human decision is needed. # Customer kyc scoring waiting for approval date Source: https://api.amlyze.com/api-reference/customer-assessment/customer-kyc-scoring-waiting-for-approval-date /webhooks/openapi_webhooks.json webhook app.amlyze.customer.riskmanagement.kyc_scoring.waiting_for_approval_date Fired when configuration is set to wait for customer approval date. # Customer retrospective completed Source: https://api.amlyze.com/api-reference/customer-assessment/customer-retrospective-completed /webhooks/openapi_webhooks.json webhook com.amlyze.customer.riskmanagement.retrospective.completed ❗ Fired ONLY on completion by a human decision. # Customer retrospective pending Source: https://api.amlyze.com/api-reference/customer-assessment/customer-retrospective-pending /webhooks/openapi_webhooks.json webhook com.amlyze.customer.riskmanagement.retrospective.pending Fired when a customer retrospective risk management process is pending and human decision is needed. # Customer assessment Source: https://api.amlyze.com/api-reference/customer-getters/customer-assessment /api/openapi_integrations.json get /api/integration-services/customer/v1/risk-scoring-assessments/{guid} This endpoint retrieves customer assessment by its unique GUID. # Customer retrospective assessment Source: https://api.amlyze.com/api-reference/customer-getters/customer-retrospective-assessment /api/openapi_integrations.json get /api/integration-services/customer/v1/retrospective-assessments/{guid} This endpoint retrieves a retrospective assessment by its unique GUID. # Customer screening Source: https://api.amlyze.com/api-reference/customer-getters/customer-screening /api/openapi_integrations.json get /api/integration-services/customer/v1/screening-alerts/{guid} This endpoint retrieves a screening alert by its unique GUID. # Customer adverse media screening completed Source: https://api.amlyze.com/api-reference/customer-screening/customer-adverse-media-screening-completed /webhooks/openapi_webhooks.json webhook app.amlyze.customer.screening.adverse_media.completed Fired when on completion by a human decision/automatically resolution. # Customer adverse media screening pending Source: https://api.amlyze.com/api-reference/customer-screening/customer-adverse-media-screening-pending /webhooks/openapi_webhooks.json webhook app.amlyze.customer.screening.adverse_media.pending Fired when a customer adverse media screening process is pending and human decision is needed. # Customer internal list screening completed Source: https://api.amlyze.com/api-reference/customer-screening/customer-internal-list-screening-completed /webhooks/openapi_webhooks.json webhook app.amlyze.customer.screening.internal_list.completed Fired when on completion by a human decision/automatically resolution. # Customer internal list screening pending Source: https://api.amlyze.com/api-reference/customer-screening/customer-internal-list-screening-pending /webhooks/openapi_webhooks.json webhook app.amlyze.customer.screening.internal_list.pending Fired when a customer internal list screening process is pending and human decision is needed. # Customer pep screening completed Source: https://api.amlyze.com/api-reference/customer-screening/customer-pep-screening-completed /webhooks/openapi_webhooks.json webhook app.amlyze.customer.screening.pep.completed Fired when on completion by a human decision/automatically resolution. # Customer pep screening pending Source: https://api.amlyze.com/api-reference/customer-screening/customer-pep-screening-pending /webhooks/openapi_webhooks.json webhook app.amlyze.customer.screening.pep.pending Fired when a customer PEP screening process is pending and human decision is needed. # Customer sanctions screening completed Source: https://api.amlyze.com/api-reference/customer-screening/customer-sanctions-screening-completed /webhooks/openapi_webhooks.json webhook app.amlyze.customer.screening.sanctions.completed Fired when on completion by a human decision/automatically resolution. # Customer sanctions screening pending Source: https://api.amlyze.com/api-reference/customer-screening/customer-sanctions-screening-pending /webhooks/openapi_webhooks.json webhook app.amlyze.customer.screening.sanctions.pending Fired when a customer sanctions screening process is pending and human decision is needed. # Batch Import of customers Source: https://api.amlyze.com/api-reference/customer/batch-import-of-customers /api/openapi_api_adapter.json post /amlyze-ws-rest/batch-customers This method sends data and creates assessments in Amlyze. Note: Customer evaluation and screening are not available in this service. # Customer updated Source: https://api.amlyze.com/api-reference/customer/customer-updated /webhooks/openapi_webhooks.json webhook com.amlyze.customer.updated Fired when a customer's data is updated. # Evaluate customer Source: https://api.amlyze.com/api-reference/customer/evaluate-customer /api/openapi_api_adapter.json post /amlyze-ws-rest/customer To initiate the scoring process, the `sourceOfRiskLevel` field in the API payload must be set to `EVALUATE`. This instructs the AMLYZE engine to run the customer's data through the active risk matrix. In contrast, sending the value `IMPORT` will only update the customer's data in the system without triggering a new risk evaluation. # Validate batch of customers without saving Source: https://api.amlyze.com/api-reference/customer/validate-batch-of-customers-without-saving /api/openapi_api_adapter.json post /amlyze-ws-rest/validate-batch-customers This method sends data only for validating JSON and does not create any assessments in AMLYZE. # Move operation to archive Source: https://api.amlyze.com/api-reference/integration-services/move-operation-to-archive /api/openapi_integrations.json delete /api/integration-services/v1/discard-operations Move operation to archive. Operations in archive are not included in retro monitoring processes. # Operation realtime completed Source: https://api.amlyze.com/api-reference/operation-assessment/operation-realtime-completed /webhooks/openapi_webhooks.json webhook app.amlyze.operation.riskmanagement.operation_realtime.completed Fired when on completion by a human decision/automatically resolution. # Operation realtime pending Source: https://api.amlyze.com/api-reference/operation-assessment/operation-realtime-pending /webhooks/openapi_webhooks.json webhook app.amlyze.operation.riskmanagement.operation_realtime.pending Fired when a real-time operation risk management process is pending and human decision is needed. # Operation assessment Source: https://api.amlyze.com/api-reference/operation-getters/operation-assessment /api/openapi_integrations.json get /api/integration-services/operation/v1/realtime-assessments/{guid} This endpoint retrieves an assessment by its unique GUID. # Operation screening Source: https://api.amlyze.com/api-reference/operation-getters/operation-screening /api/openapi_integrations.json get /api/integration-services/operation/v1/screening-alerts/{guid} This endpoint retrieves a screening alert by its unique GUID. # Operation Reconciliation Source: https://api.amlyze.com/api-reference/operation-reconciliation/operation-reconciliation /api/openapi_integrations.json get /api/integration-services/v1/operations-reconciliation Returns all registered operations for a given timeframe. # Batch import of operations Source: https://api.amlyze.com/api-reference/operation/batch-import-of-operations /api/openapi_api_adapter.json post /amlyze-ws-rest/batch-operations # Evaluate operation Source: https://api.amlyze.com/api-reference/operation/evaluate-operation /api/openapi_api_adapter.json post /amlyze-ws-rest/operation To initiate the scoring process, the `sourceOfRiskLevel` field in the API payload must be set to `EVALUATE`. This instructs the AMLYZE engine to run the operation's data through the active risk matrix. In contrast, sending the value `IMPORT` will only update the operation's data in the system without triggering a new risk evaluation. # Validate Batch Operations Source: https://api.amlyze.com/api-reference/operation/validate-batch-operations /api/openapi_api_adapter.json post /amlyze-ws-rest/validate-batch-operations # Related entity adverse media screening completed Source: https://api.amlyze.com/api-reference/related-entity-screening/related-entity-adverse-media-screening-completed /webhooks/openapi_webhooks.json webhook app.amlyze.related_entity.screening.adverse_media.completed Fired when on completion by a human decision/automatically resolution. # Related entity adverse media screening pending Source: https://api.amlyze.com/api-reference/related-entity-screening/related-entity-adverse-media-screening-pending /webhooks/openapi_webhooks.json webhook app.amlyze.related_entity.screening.adverse_media.pending Fired when a related entity adverse media screening process is pending and human decision is needed. # Related entity internal list screening completed Source: https://api.amlyze.com/api-reference/related-entity-screening/related-entity-internal-list-screening-completed /webhooks/openapi_webhooks.json webhook app.amlyze.related_entity.screening.internal_list.completed Fired when on completion by a human decision/automatically resolution. # Related entity internal list screening pending Source: https://api.amlyze.com/api-reference/related-entity-screening/related-entity-internal-list-screening-pending /webhooks/openapi_webhooks.json webhook app.amlyze.related_entity.screening.internal_list.pending Fired when a related entity internal list screening process is pending and human decision is needed. # Related entity pep screening completed Source: https://api.amlyze.com/api-reference/related-entity-screening/related-entity-pep-screening-completed /webhooks/openapi_webhooks.json webhook app.amlyze.related_entity.screening.pep.completed Fired when on completion by a human decision/automatically resolution. # Related entity pep screening pending Source: https://api.amlyze.com/api-reference/related-entity-screening/related-entity-pep-screening-pending /webhooks/openapi_webhooks.json webhook app.amlyze.related_entity.screening.pep.pending Fired when a related entity PEP screening process is pending and human decision is needed. # Related entity sanctions screening completed Source: https://api.amlyze.com/api-reference/related-entity-screening/related-entity-sanctions-screening-completed /webhooks/openapi_webhooks.json webhook app.amlyze.related_entity.screening.sanctions.completed Fired when on completion by a human decision/automatically resolution. # Related entity sanctions screening pending Source: https://api.amlyze.com/api-reference/related-entity-screening/related-entity-sanctions-screening-pending /webhooks/openapi_webhooks.json webhook app.amlyze.related_entity.screening.sanctions.pending Fired when a related entity sanctions screening process is pending and human decision is needed. # Simplified customer import Source: https://api.amlyze.com/api-reference/simplified-customer/simplified-customer-import /api/openapi_api_adapter.json post /amlyze-ws-rest/simplifiedCustomer This section provides information on how to generate a Simplified Customer for individuals or organizations. # Account Source: https://api.amlyze.com/pages/account Learn about Account resource An **Account** represents a financial account or a similar unique identifier that links transactions to a specific customer. To monitor transactions and detect suspicious activity, you must first link an account to a specific Customer profile. Within AMLYZE, an account is identified by a unique external identifier. If the external ID is not provided, the account is identified instead by the combination of `accountNumber`, `currency`, and `bic`. For businesses that do not use traditional bank accounts — such as payment gateways — the `accountNumber` can be any unique identifier, like a phone number or an email address. Its primary function remains the same: to serve as the link between a customer and their financial operations. By importing these accounts, our system can track operations and associate them with the correct individual or organization. ## Account Balances To make monitoring even more effective, you can track and update the Balance for any account. Providing periodic balance updates allows our system to look beyond individual transactions. By knowing the current "state" of an account, the monitoring rules can detect sophisticated patterns, such as sudden wealth spikes or accounts being emptied suspiciously fast. ## Key Details * We support various formats for account numbers. You can use standard IBANs, local bank account numbers, or even crypto wallet addresses. * Every account must be attached to a customer. An account cannot exist in the system without an owner. # Architecture Source: https://api.amlyze.com/pages/architecture AMLYZE works in the background (**asynchronously**). This means that when you send data, you don't have to wait for the full analysis to finish before receiving a response. ### How Requests Work When you send a request for evaluating a customer or an operation, the system follows these steps: 1. **Validation:** The system checks that the data format is correct. 2. **Creation:** It saves the information and triggers an internal event. 3. **Response:** It sends you a simple `REQUEST_ACCEPTED` or `REQUEST_REJECTED` message. ### Receiving Results (Webhooks) Because the analysis happens in the background, you must provide an **endpoint (URL)** where AMLYZE can send the results. * **Flexible Routing:** You can set up multiple endpoints. * **Smart Filtering:** You can choose to send different types of events (like screening vs. risk scoring) to different URLs. * **Business Unit Separation:** Each Business Unit can have its own dedicated endpoint to keep data organized. ### Integration Flow Async Integration Flow ### A Note on Timing In some rare cases, the analysis result might reach your endpoint **before** you receive the `REQUEST_ACCEPTED` response from the initial request. Your system should be built to handle these results immediately, even if the original task hasn't "officially" finished in your logs yet. # Access & Security Source: https://api.amlyze.com/pages/authorization Access to the API service is secured through a multi-layer approach: network-level IP Access Control Lists (ACL) and application-level Token Authorization. Both mechanisms are required for successful requests. ## IP Access Control (ACL) Your server's specific IP address(es) must be explicitly authorized to communicate with the API. * **Provisioning**: Your IP addresses are added to the ACL during the onboarding process. * **Updates**: To add or remove IP addresses after onboarding, you must contact Support. ## Authorization (API Token) Once network access is granted via the ACL, you must authorize your requests using an API token. * **Provisioning**: Your unique API token is issued to you during the onboarding process. * **Header Format**: All requests must include the HTTP Authorization header using the Bearer schema. * **Updates**: If you need to generate a new token or revoke an existing one, please contact Support. Your API token carries full administrative privileges. Keep it secure. Never share your secret token in publicly accessible areas such as GitHub repositories, client-side code, or public forums. ```bash Authorized Request theme={null} curl --request POST \ --url /amlyze-ws-rest/customer \ --header "Authorization: Bearer sup3r_s3cr37_@pi_|<3y_3x4mpl3" \ --data '{...}' ``` ```json Unauthorized Response (401) theme={null} { "error": { "code": "unauthorized" } } ``` # Business Unit Source: https://api.amlyze.com/pages/business_unit Learn about Business Unit A **Business Unit** is a way to organize and separate data within AMLYZE. You can use them to group customers and operations based on how your company is structured. ## Common Use Cases You can set up Business Units to fit your specific needs. Common examples include: * **Geography:** Separate data by country or legal jurisdiction. * **White-labeling:** Create a distinct unit for each brand you support. * **Product Lines:** Keep different business branches or service types separate. ## Key Benefits * **Unique Configurations:** Each unit can have its own specific monitoring rules and settings. * **Data Privacy:** Information is siloed, meaning data from one unit isn't mixed with another unless you want it to be. * **Flexible Access:** You can assign users to a single unit or give them access to see everything across the entire company. # Communication Number Source: https://api.amlyze.com/pages/communication_number Communication number unique identifier Each request that is related to customer, account or operation object creation in the system is associated with request identifier called `communicationNumber`. Provided value **must be unique for each request and cannot be reused**. Trying to reuse already used value will result in error. This logic applies to both failed and succeeded requests. To expedite the resolution process, provide the `communicationNumber` when you contact us about a specific request. # Contract Source: https://api.amlyze.com/pages/contract Learn about Contract resource A **Contract** is a flexible resource used to store extra details about a customer's relationship with you. It doesn't have strict built-in logic, making it a "blank canvas" for your specific data needs. ## How It Works * **Fixed Fields:** Some predefined fields such as contract code, start and end dates, etc are used in the web application when displaying the contract information. * **Key-Value Pairs:** You can add any information you find useful as additional properties using a simple key-value format. * **Status Tracking:** Each contract includes a simple indicator to show if it is currently **active** or **inactive**. * **Risk Context:** While the contract itself doesn't perform actions, our system can use its details to help with **risk assessment**. * **Linking:** It is possible to link the contract to the [customer](/pages/customer) or the [account](/pages/account). ## Why Use Contracts? You can use contracts to pass specific details that help our monitoring rules. For example, you might include the "Contract Type", "Expected Monthly Volume", or "Source of Wealth". If a customer's activity doesn't match these contract details, the system can flag it for review. # Customer Source: https://api.amlyze.com/pages/customer Learn about Customer resource A **Customer** is the digital profile for any person or organization you do business with. Creating a customer profile allows you to store KYC (Know Your Customer) data and monitor their activities for potential money laundering risks. In our system, you can create customers as either **Individuals** or **Organizations**. ## Regular vs. Simplified Customers Depending on how much information you have, you can choose between two setup types: * **Regular Customer**: Use this for full monitoring. You provide all necessary KYC data so the system can perform a complete risk assessment. This is the standard for your ongoing compliance. * **Simplified Customer**: Use this when you have limited data. It requires fewer mandatory fields and is designed for quick **screening**. Simplified customers cannot be risk-scored. Simplified customer is created with default account, where both account number and account external ID is equal to the customer external ID. ## Upgrading Profiles You can upgrade a **Simplified Customer** to a **Regular Customer** at any time by adding the missing information. However, once a profile becomes a Regular Customer, it cannot be reverted to the Simplified version. # Importing Data Source: https://api.amlyze.com/pages/data_import Learn how to import data into AMLYZE ## Initial Integration The relationship between these core objects dictates a clear, sequential data submission flow that must be followed. The Customer profile serves as the central hub where all data, alerts, and case history for a single entity are aggregated and made accessible for investigation. Start by creating profiles for the people or companies you want to monitor. This is the foundation of your data. You can send customers [one by one](/api-reference/customer/evaluate-customer) or use a [batch import](/api-reference/customer/batch-import-of-customers) to upload many at once. Once a customer exists, you can add their accounts. The system needs these accounts to know where money is coming from or going to. Link accounts to existing customers using either [single requests](/api-reference/account/account-import) or [batch imports](/api-reference/account/batch-import-of-accounts). Now that the customers and accounts are set up, you can begin importing operations (transactions). The system will automatically check these against your monitoring rules. Feed the data into the system via [batch import](/api-reference/operation/batch-import-of-operations) for historical data or [single requests](/api-reference/operation/evaluate-operation) for real-time monitoring. # Data Lifecycle & Risk Evaluation Source: https://api.amlyze.com/pages/data_lifecycle Manage the creation and modification of customer data. Granular control over how data is persisted (`action`) and how risk assessment logic is applied to that data (`sourceOfRiskLevel`) allows the API to serve multiple use cases, from historic data migration (where risk is already known) to live customer onboarding (where risk must be calculated in real-time). ## Request Control Parameters The behavior of the endpoints is controlled by two key attributes in the request body. | Attribute | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`action`** | Determines the persistence strategy.
• `CREATE`: Creates a new record. Fails if the record exists.
• `UPDATE`: Modifies an existing record. | | **`sourceOfRiskLevel`** | Determines if the Risk Engine should trigger.
• `IMPORT`: Bypasses evaluation. Used when migrating data or manually overriding risk.
• `EVALUATE`: Triggers the Risk Engine to calculate risk based on the payload. | ## Lifecycle Matrix The combination of `action` and `sourceOfRiskLevel` results in four distinct processing behaviors. | Combination | Behavior Description | Typical Use Case | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **1. CREATE + IMPORT** | **Direct Ingestion**
Creates a new record but skips the risk engine. The risk level provided in the payload is saved "as is". | • Data Migration
• System Restoration
• Importing pre-vetted archives | | **2. CREATE + EVALUATE** | **New Assessment**
Creates a new record and immediately runs the risk engine to calculate and assign a risk level. | • New Customer Onboarding
• First-time application processing | | **3. UPDATE + IMPORT** | **Manual Override / Correction**
Updates existing attributes without re-triggering risk calculation. | • Fixing typos (e.g., name misspelling)
• Admin manual override of a risk score | | **4. UPDATE + EVALUATE** | **Re-Assessment**
Updates attributes and re-runs the risk engine to determine if the changes affect the risk profile. | • KYC Refresh (Periodic Review)
• Change in customer circumstances (e.g., new country of residence) | # Errors Source: https://api.amlyze.com/pages/errors Introduction to Errors AMLYZE uses conventional HTTP response codes to indicate the success or failure of an API request. In general: * Codes in the **2xx** range indicate **success**. * Codes in the **4xx** range indicate a **business error** that failed given the information provided (e.g., a required parameter was omitted, provided value is incorrect, etc.). * Codes in the **5xx** range indicate an **internal error** within AMLYZE servers (these are rare). **4xx** errors include an error code and description that briefly explains the error reported. ## List of Errors Some error codes contain `[[dynamicValue]]` - this value in the description is replaced by actual value based on the context. It could be value from classifier or from the enum or some other aspect that is dynamic and might change. Never rely on the error description as a case for handling. Always use error code for that. Descriptions change frequently to reflect new contextual information available in the api or to provide better understanding of the problem space. | Error Code | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | | | AccountExtId is mandatory | | | AccountNumber is mandatory | | | ActivityInRestrictedRegionDescription | | | BirthCountry | | | BirthDate | | | BusinessEntityExtId is mandatory | | | CitizenshipCountry | | | CompanyAssetValue | | | EstablishmentDate | | | FirstName | | | GIIN | | | Given customer exists as regular customer | | | LastName | | | LegalForm | | | LEI | | | LicenseDescription | | | NumberOfAudits | | | NumberOfEmployees | | | OrganizationalStructureDescription | | | PeriodsOfAuditsInYears | | | PermanentResidenceCountry | | | RegionOfActivityDescription | | | SecondCitizenshipCountry | | | ThirdPartyServicesUsedDescription | | | Title | | | TradingName | | 001 | CommunicationNumber is mandatory | | 001 | Currency does not exist in Amlyze | | 001 | Requester is mandatory | | 002 | CLOSED account requires closingDate | | 002 | Invalid Account status, allowed values: ACTIVE, SUSPENDED, CLOSED; | | 002 | not closed account cant have closing date | | 003 | Account already linked with other customer | | 005 | Given bic does not belong to your institution | | 005 | when using external account, bic is mandatory | | 006 | Given AccountType does not exist in Amlyze | | 007 | openingDate is mandatory | | 400 | Cannot register account for lead customer | | 404 | BusinessEntity with given extId does not exist in amlyze | | 500 | failed processing account balance | | 500 | failed Processing account | | 500 | failed processing contract | | 500 | failed processing customer | | 500 | failed Processing operation | | 500 | failed processing simplified customer | | A001 | The additional property code is mandatory. | | A001 | The additional property title is mandatory. | | A001 | The boolean value of '\[\[dynamicValue]]' is invalid '\[\[dynamicValue]]' true/false. | | A001 | The value of '\[\[dynamicValue]]' is in an invalid format 'yyyy-MM-dd' '\[\[dynamicValue]]'. | | A001 | The value of '\[\[dynamicValue]]' is in an invalid format 'yyyy-MM-dd'T'HH:mm:ss.SSS'Z'' '\[\[dynamicValue]]'. | | A001 | The value of '\[\[dynamicValue]]' is out of bounds or in an invalid format '\[\[dynamicValue]]'. | | A01 | AmountInEquivalent or deprecated AmountInEuro is mandatory and must be greater than 0. | | A01 | AmountInEquivalent is mandatory and must be greater than 0. | | A02 | EuroExchangeRate deprecated must be greater than 0. | | A02 | ExchangeRate must be greater than 0. | | AC01 | ActivityType is mandatory | | AC02 | ActivityType must be defined in Amlyze | | ADR01 | AddressType is mandatory. | | ADR02 | AddressType is not defined in amlyze. | | ADR02 | Country is mandatory and cant be empty | | ADR02 | Country is mandatory and must exist in Amlyze | | AR01 | AppealReasonType is mandatory and must defined in Amlyze | | AR02 | AppealReasonType is mandatory and cant be empty | | AV01 | AdditionalValue.Code is mandatory | | AV02 | AdditionalValue.Description is mandatory | | AV03 | AdditionalValue.Value is mandatory | | AV04 | AdditionalValue.Datatype is mandatory | | AV05 | Dublicate code in additionalValues, \[\[dynamicValue]] | | AV06 | Bad datatype valueCode: \[\[dynamicValue]] | | AV07 | bad value for \[\[dynamicValue]] valueCode: \[\[dynamicValue]] | | AV07 | bad value for \[\[dynamicValue]] format: 'yyyy-MM-dd HH:mm:ss.SSSZ' valueCode: \[\[dynamicValue]] | | AV07 | bad value for \[\[dynamicValue]] format: 'yyyy-MM-dd HH:mm:ss.SSSZ' valueCode: \[\[dynamicValue]] | | AV07 | bad value for \[\[dynamicValue]] format: 'yyyy-MM-dd' valueCode: \[\[dynamicValue]] | | AV07 | bad value for \[\[dynamicValue]] format: 'yyyy-MM-dd' valueCode: \[\[dynamicValue]] | | AV07 | bad value for \[\[dynamicValue]] values: true false' valueCode: \[\[dynamicValue]] | | AV07 | bad value for \[\[dynamicValue]] valueCode: \[\[dynamicValue]] | | C001 | The account balance external ID is mandatory. | | C001 | The account balance type is mandatory. | | C001 | The contract external ID is mandatory. | | C001 | The contract type is mandatory. | | C001 | The customer external ID is mandatory. | | C001 | The requester is mandatory. | | C002 | A account balance type '\[\[dynamicValue]]' was not found in the system. | | C002 | A contract type '\[\[dynamicValue]]' was not found in the system. | | C002 | A contract with the external ID '\[\[dynamicValue]]' already exists. The contract can only be updated. | | C002 | A contract with the external ID '\[\[dynamicValue]]' does not exist. The contract can only be created. | | C002 | A customer with the external ID '\[\[dynamicValue]]' was not found. | | C002 | additionalProperties\[\[\[dynamicValue]]]. | | C002 | An account with the external ID '\[\[dynamicValue]]' was not found. | | C002 | CustomerExtId is mandatory. | | C004 | Cannot update not existing customer, use Action = CREATE | | C004 | Customer already exists | | C005 | DELETE not yet implemented, contact Amlyze support | | C006 | Requester is mandatory. | | C007 | RiskManagementCategory does not exist in Amlyze | | C007 | RiskManagementCategory is mandatory. | | C008.E01 | When source of risk level EVALUATE. RiskLevel can't be provided | | C008.I01 | When source of risk level IMPORT. RiskLevel is mandatory, values: NONE, LOW, MEDIUM, HIGH, EXTREME | | C008.I02 | When source of risk level IMPORT. 'Lead' risk management category is forbidden | | C008 | SourceOfRiskLevel is mandatory. Values: IMPORT, EVALUATE | | C009 | When importing, CustomerStatus is mandatory. | | C010 | EntityType is mandatory. | | C012 | ApplicationDate is mandatory | | C013 | ClosingDate is mandatory for CLOSED CustomerStatus | | C013a | ClosingDate can not exist for not CLOSED CustomerStatus | | C014 | EntityType is mandatory | | C014 | Field not allowed for INDIVIDUAL. Field: | | C015 | Field not allowed for ORGANIZATION. Field: | | C016.I06 | BirthCountry not defined in Amlyze | | C016.I06 | Problem with field for INDIVIDUAL type customer. CitizenshipCountry not found in amlyze | | C016.I07 | CitizenshipCountry not defined in Amlyze | | C016.I08 | permanentResidenceCountry not defined in Amlyze | | C016.I08 | SecondCitizenshipCountry not defined in Amlyze | | C016 | For INDIVIDUAL type customer | | C016 | Problem with field for INDIVIDUAL type customer. | | C016 | Problem with relatedEntities. | | C016 | Problem with relatedEntity (index: \[\[dynamicValue]]). | | C017 | For ORGANIZATION type customer | | C017 | Problem with field for ORGANIZATION type customer. | | CA01 | CountryOfActivity must be defined | | CA01 | CountryOfActivity not found in Amlyze | | CARD\_REFUND\_op | for card\_refund subtype, creditor must be your customer | | Co1 | ContactType is mandatory. values: MOBILEPHONE, FIXEDPHONE, EMAIL, WEBSITE | | Co2 | ContactDetails is mandatory | | COTP01 | CountryOfTaxPayment cant be empty | | COTP01 | CountryOfTaxPayment not found in Amlyze | | DOC01 | EntityType is mandatory. values : INDIVIDUAL, ORGANIZATION | | DOC02 | IdentityDocumentType is mandatory. values: PASSPORT IDENTITYCARD, RESIDENCEPERMIT, DRIVINGLICENSE, REGISTRATIONCERTIFICATE, OTHER | | DOC03 | DocumentNumber is mandatory. | | DOC04 | DocumentIssueDate is mandatory. | | DOC06 | DocumentIssueCountry is mandatory and must exist in Amlyze | | DOC07 | DocumentIssueAuthority is mandatory | | DT01 | TurnoverType is mandatory | | DT01 | TurnoverType must exist in amlyze | | DT02 | At least one value must be specified (FROM, TO | | DT03 | TurnoverRange is mandatory. Values: SINGLE, DAILY, MONTHLY, ANNUAL | | FOA01 | FieldOfActivity.Student.Country is invalid | | FOA02 | PensionCountry is invalid | | I01 | FirstName is mandatory | | I02 | LastName is mandatory | | IS01 | IncomeSourceType is mandatory and exist in Amlyze | | IS01 | IntroductionSource not found in amlyze | | IS02 | IntroductionSource not found in amlyze | | LEAD | Cannot demote existing customer to Lead riskManagementCategory | | legalForm | LegalForm must exist in Amlyze | | MCC01 | Invalid MerchantCountryCode | | O001 | CommunicationNumber already used in amlyze | | O001 | CommunicationNumber is mandatory | | O001 | CommunicationNumber was already used in Amlyze | | O0018 | OperationDateTime is mandatory. | | O002 | OperationExtId is mandatory | | O002 | Requester is mandatory | | O003 | Action is not supported. | | O004 | SourceOfRiskLevel is mandatory, allowed values: IMPORT / EVALUATE. | | O005 | Operation with given OperationExtId already exists in Amlyze | | O005 | Operation with given OperationExtId does not exist in Amlyze | | O006 | OperationType is mandatory | | O006 | Problem with OperationType \[\[dynamicValue]]. CardOperationSubType is mandatory | | O006 | Problem with OperationType \[\[dynamicValue]]. CardOperationSubType\[\[dynamicValue]] requires \[\[dynamicValue]]direction | | O006 | Problem with OperationType \[\[dynamicValue]]. Subtype not found in Amlyze | | O006 | Problem with OperationType \[\[dynamicValue]]. | | O007 | ListOperationParty is mandatory and can't be empty. | | O007 | Problem with operation party (index: \[\[dynamicValue]]). | | O008 | Problem with SourceOfRiskLevel \[\[dynamicValue]]. | | O008 | SourceOfRiskLevel is mandatory. | | O009 | OperationDateTime is mandatory. | | O01 | Title is mandatory | | O010 | SourceCountry is mandatory, check country classifier codes for allowed values. | | O010 | SourceCountry is mandatory, check country classifier codes for allowed values. | | O011 | DestinationCountry is mandatory, check country classifier codes for allowed values. | | O011 | DestinationCountry is mandatory, check country classifier codes for allowed values. | | O012 | Currency is mandatory, check Currency classifier codes for allowed values. | | O013 | Amount is mandatory and must be > 0. | | O013 | Amount is mandatory and must be greater than 0. | | O013 | When currency != \[\[dynamicValue]]. | | O013e | Despite currency = \[\[dynamicValue]], AmountInEquivalent differs from Amount | | O013e | Despite currency = \[\[dynamicValue]], AmountInEuro differs from Amount | | O015 | For not INTERNAL operation financialFlowDirection value cant be 'NULL' | | O015a | Invalid FinancialFlowDirection. Your institution DEBTOR found for INCOMING operation | | O015b | Invalid FinancialFlowDirection. Your institution CREDITOR found for OUTGOING operation | | O016 | RiskManagementCategory does not exist in Amlyze | | O016 | RiskManagementCategory is mandatory | | O019 | OperationParties must contain CREDITOR | | O02 | RegistrationCountry is mandatory | | O020 | OperationParties must contain DEBTOR | | O021 | Description is mandatory | | O021 | For cryptoExchange at least one currency must be crypto | | O021 | For cryptoExchange operationPartyCurrencies must differ | | O021 | PIS operation financialFlowDirection can't be OUTGOING | | O03 | LegalForm is mandatory | | OP\_roles | for INCOMING operation your's customer party role must be CREDITOR | | OP\_roles | for OUTGOING operation your's customer party role must be DEBTOR | | Op00 | AccountNumber or CardNumber is mandatory. for card operation | | OP00 | operation party title or firstName or lastName or cardHolderName is mandatory | | OP01 | AccountNumber is mandatory. | | Op01 | Invalid operation party count. Range: min 1 max 4. | | OP02 | BIC is mandatory. | | Op02 | Invalid count of operation parties for \[\[dynamicValue]] operationType | | Op02 | Invalid count of your institution operation parties for \[\[dynamicValue]] operationType | | Op03 | Invalid count of your institution operation parties for \[\[dynamicValue]] operationType | | Op04 | Currency is mandatory, check Currency classifier codes for allowed values | | OP04 | EntityType is mandatory, values: INDIVIDUAL, ORGANIZATION, UNKNOWN | | Op04 | No operation party account related to your institution BIC, or Customer | | OP05 | PartyRole is mandatory, possible values: CREDITOR, ULTIMATE\_CREDITOR | | OP05 | PartyRole is mandatory, possible values: DEBTOR, CREDITOR, ULTIMATE\_DEBTOR, ULTIMATE\_CREDITOR | | OP06 | Account registered to your institution, Account found in amlyze, but customer not found in Amlyze | | OP06 | Account registered to your institution, Account found in Amlyze, but customer not found in Amlyze | | OP06 | The value for the country in the party is not within the allowed values specified by the country classifier. | | Op19 | CREDITOR bic is mandatory. | | OPi01 | For INDIVIDUAL party firstName + lastName, title is mandatory. | | OPi01 | For INDIVIDUAL party firstName + lastName, title or identifier is mandatory. | | OPi01 | For UNKNOWN party title is mandatory. | | OPi01 | For UNKNOWN party title or identifier is mandatory. | | OPo01 | For ORGANIZATION party firstName or lastName cannot be provided. | | OPo01 | For ORGANIZATION party title is mandatory. | | OPo01 | For ORGANIZATION party title or identifier is mandatory. | | OPo01 | For UNKNOWN party firstName or lastName cannot be provided. | | OST01 | ServiceType not found in Amlyze | | OST02 | ServiceType not found in Amlyze | | Ot01 | \[\[dynamicValue]] is not defined in Amlyze. Check Operation type classifier for available values. | | Ot02 | Problem with OperationParties. | | PP01 | PaymentPurposeType does not exist in Amlyze | | PP02 | TurnoverDirection is invalid | | Q001 | InitialDepositCurrency not found in amlyze | | Q002 | Problem with Customer BusinessEntityDocument index = \[\[dynamicValue]]. | | Q003 | Problem with Customer Contact index = \[\[dynamicValue]]. | | Q004 | Problem with Address (index: \[\[dynamicValue]]). classifier \[\[dynamicValue]] | | Q004 | Problem with Address (index: \[\[dynamicValue]]). | | Q006 | Problem with IncomeSource (index: \[\[dynamicValue]]). | | Q007 | Problem with activity (index: \[\[dynamicValue]]). | | Q008 | Problem with RegionOfActivity (index: \[\[dynamicValue]]). | | Q009 | Problem with CountryOfActivity (index: \[\[dynamicValue]]). | | Q010 | Problem with ListAppealReason (index: \[\[dynamicValue]]). | | Q011 | Problem with IntroductionSource (index: \[\[dynamicValue]]). | | Q012 | Problem with OrderedService (index: \[\[dynamicValue]]). | | Q013 | Problem with DeclaredTurnover (index: \[\[dynamicValue]]). | | Q014 | Problem with PaymentCountry (index: \[\[dynamicValue]]). | | Q015 | Problem with PaymentPurpose (index: \[\[dynamicValue]]). | | Q017 | CountryOfTaxPayment (index: \[\[dynamicValue]]). | | RA01 | RegionOfActivity must be defined | | RA01 | RegionOfActivity not found in Amlyze | | RC01 | PaymentCountry not found in Amlyze | | RC02 | PaymentCountry cant be empty | | RC02 | TurnoverDirection is invalid | | RE00 | first and last name or title is mandatory for Individual | | RE00 | Title is mandatory for ORGANIZATION | | RE00 | Title or firstName + lastName is mandatory | | RE01 | Relation type is mandatory | | RE01 | Relation type is not defined in Amlyze | | RE02 | EntityType is mandatory. | | RE03 | BirthCountry not defined in Amlyze | | RE03 | Country not defined in Amlyze | | RE05 | LegalForm not found in Amlyze | | RE06 | Problem with Address (index: \[\[dynamicValue]]). | | RE06 | Problem with Contact (index: \[\[dynamicValue]]). | | RE08 | Problem with BusinessEntityDocuments (index: \[\[dynamicValue]]). | | RE09 | Problem with IncomeSource (index: \[\[dynamicValue]]). | | RE10 | Problem with activity (index: \[\[dynamicValue]]). | | RE11 | Problem with RegionOfActivity (index: \[\[dynamicValue]]). | | RE12 | Problem with CountryOfActivity (index: \[\[dynamicValue]]). | | RE13 | Related entity list got duplicates (index: \[\[dynamicValue]]) and \[\[dynamicValue]]. | | REG | registrationCountry is invalid | | REG | registrationCountry must exist in Amlyze | | SCR01 | screening process is undefined: \[\[dynamicValue]] | | SEC1 | Business unit is mandatory | | SEC1 | Tenant header '\[\[dynamicValue]]' is mandatory | | SEC3 | Tenant '\[\[dynamicValue]]' business unit '\[\[dynamicValue]]' does not exist | | SoRL01 | OperationStatus is mandatory for IMPORT operation. Possible values: REJECTED / EXECUTED. | | SoRL02 | OperationStatus must be empty for EVALUATE operation | | SOV01 | SourceOfWealth \[\[dynamicValue]] is not defined in amlyze | ```json 200 theme={null} {"resultType": "REQUEST_ACCEPTED"} ``` ```json 400 theme={null} { "resultType": "REQUEST_REJECTED", "errorCode": "C008.I01", "errorDescription": "When source of risk level IMPORT. RiskLevel is mandatory, values: NONE, LOW, MEDIUM, HIGH, EXTREME" } ``` ```json 400 (2) theme={null} { "timestamp": "2025-12-16T13:50:34.272+00:00", "status": 400, "error": "Bad Request", "path": "/amlyze-ws-rest/customer" } ``` ```json 400 (3) theme={null} { "errors": [ "Field: 'communicationNumber', message: 'CommunicationNumber is mandatory'" ] } ``` ```json 401 theme={null} { "error": { "code": "unauthorized" } } ``` ```json 404 theme={null} { "timestamp": "2025-12-16T13:51:12.162+00:00", "status": 404, "error": "Not Found", "path": "/amlyze-ws-rest/not-found" } ``` ```json 500 theme={null} { "resultType": "REQUEST_REJECTED", "errorCode": "500", "errorDescription": "failed processing customer" } ``` Error code. Error description. Result type. List of error descriptions. Timestamp when the error occurred. HTTP status code. Error description. Api path in which error occurred. # Introduction Source: https://api.amlyze.com/pages/introduction ## The AMLYZE Solution The AMLYZE API serves as the primary gateway to the broader **AMLYZE** ecosystem, a modular, cloud-native platform engineered to address the full spectrum of Anti-Money Laundering (AML) compliance obligations. Built for high availability and security, the solution is designed with an "API-first" philosophy. It allows financial institutions to seamlessly integrate complex compliance workflows—from data submission to decisioning—directly into their core banking or financial systems. The platform operates on a strict core data model that links three primary objects: * **Customers:** The foundational entities (individuals or organizations). * **Accounts:** Financial identifiers linked to customers. * **Operations:** Transactions associated with accounts. This interconnected structure ensures that all monitoring and screening activities are contextually accurate, audit-ready, and correctly attributed to the specific entity. ## The AMLYZE API The AMLYZE API is a comprehensive suite of tools designed to embed automated Anti-Money Laundering (AML) compliance workflows directly into your application. It provides the necessary endpoints to manage customer lifecycle, screen entities against various watchlists, and monitor transactions in both real-time and retrospectively. The AMLYZE API delivers three core capabilities to automate your compliance program: * **Customer Risk Assessment:** Enables dynamic risk scoring for new and existing clients through a powerful, configurable rule engine to automate risk-based decisioning. * **Transaction Monitoring:** Facilitates both real-time (pre-transaction) and retrospective (post-transaction) analysis of financial operations to detect and flag suspicious activity. * **Screening:** Checks customers, related entities (like UBOs or directors), and transaction counterparties against global Sanctions, Politically Exposed Persons (PEP), Adverse Media, and custom internal watchlists. In addition to supporting single-object requests, the AMLYZE API also supports bulk imports of customers, operations, and accounts. While the API facilitates the immediate transmission of data, the AMLYZE solution utilizes **webhooks** for asynchronous communication. This ensures that time-intensive processes—such as detailed retrospective analysis or manual case investigations—do not impact the performance of your client-facing application. Results and status updates are pushed back to your system automatically as they are completed. To support time-critical flows like instant payments (e.g., SEPA Instant), the API employs a dual-queue architecture, routing real-time operations to a dedicated "Priority Queue" distinct from the "Regular Queue" used for background tasks. This segregation guarantees that instant payments receive near-immediate compliance decisions, meeting strict SLAs without interference from heavy batch processing loads. Follow the usual recommended integration flow guide. Explore endpoints, parameters, and examples for AMLYZE API. # Connect via MCP Source: https://api.amlyze.com/pages/mcp Connect the AMLYZE documentation MCP server to your AI assistant to search and read the docs without leaving your editor. The AMLYZE documentation is available as a **Model Context Protocol (MCP) server**. Connecting it lets your AI assistant search and read these docs directly — endpoint contracts, field definitions, validation rules, and error codes — as live context while you build your integration. ## What it is MCP is an open standard that lets AI tools pull in external sources of context. The AMLYZE docs site exposes an MCP server, so any MCP-compatible assistant — Claude Code, Claude Desktop, Cursor, VS Code, and others — can query this documentation on demand instead of relying on a model's training snapshot. The server is **read-only** and exposes only the public documentation you already see on this site. It does not expose account data, customer data, API tokens, or any other credentials. ## What you can do Once connected, your assistant can: * **Search the docs semantically** — ask a question in plain language and pull the most relevant pages. * **Read full pages and API-reference detail** — request and response shapes, field-level descriptions, validation rules, and error codes — straight into your IDE or chat. * **Stay current** — answers reflect the live documentation rather than a model's training cut-off. ## Server URL Your MCP server URL is `https://api.amlyze.com/mcp`. Mintlify auto-hosts the MCP server at `/mcp` for the deployed documentation domain. Before publishing, confirm the server is enabled and reachable at this address. ## Connect your client Run this in your terminal: ```bash theme={null} claude mcp add --transport http amlyze-docs https://api.amlyze.com/mcp ``` Run `claude mcp list` (or `/mcp` inside a session) and confirm `amlyze-docs` appears. See the [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for details. Create or update your Codex `config.toml` (project-level `.codex/config.toml`, or global `~/.codex/config.toml`): ```toml theme={null} [mcp_servers."amlyze-docs"] url = "https://api.amlyze.com/mcp" ``` Restart Codex so it picks up the new server. Run `/mcp` and confirm `amlyze-docs` is in the configured MCP servers. Prefer the `config.toml` entry over `codex mcp add --url`: some hosted MCP providers trigger an OAuth flow even when the documentation endpoint is publicly readable. Run this in your terminal: ```bash theme={null} copilot mcp add --transport http amlyze-docs https://api.amlyze.com/mcp ``` Restart Copilot CLI so it picks up the new server. Skipping this can trigger an OAuth prompt, even though the docs endpoint is public. Run `/mcp` in Copilot CLI and confirm `amlyze-docs` is listed. See the [Copilot CLI MCP docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) for details. **Quickest path:** on any page of this site, open the contextual menu in the page header and choose **Copy MCP install command** to copy the install command, or **Copy MCP server URL** to grab the URL directly — no need to type it by hand. Client MCP setup changes frequently. Verify the exact command or configuration against each client's current MCP documentation before relying on it. # Operation Source: https://api.amlyze.com/pages/operation **Operation**, also referred to as a transaction, represents the financial activity. Every Operation sent must be linked to at least one [Account](/pages/account) that already exists in the system. This ensures that every transaction is associated with a specific [Customer](/pages/customer), which is a critical requirement for effective monitoring. This linkage applies to at least one party in the transaction. Each transaction can have up to four participants — two direct parties (sender and receiver) and two ultimate parties. At least one direct party must be your customer; the others may be customers or external counterparties. To keep integration simple, we use a [single endpoint](/api-reference/operation/evaluate-operation) for all transaction data. The specific details required depend on the type of operation you are reporting. ## Operation Types | Operation Type | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SEPA` | A cross-border payment initiative by the European Union to simplify bank transfers denominated in euros. It essentially treats cross-border euro payments exactly like domestic payments. This type covers both SEPA Credit Transfer and SEPA Instant. | | `SWIFT` | Not a payment system itself, but rather a highly secure global messaging network used by banks to transmit instructions for international wire transfers. | | `CARD_CASH` | A direct operation between the cardholder and the card issuer/ATM network — for example, an ATM withdrawal made using a credit or debit card. | | `CARD_PAYMENT` | A standard transaction using a payment card (credit, debit, or prepaid) to purchase goods or services at a Point of Sale (POS) or online. | | `CASH` | The physical movement of fiat currency into or out of a bank account, typically conducted at a branch. | | `CASH_TRANSFER` | A remittance service where funds are moved primarily via cash-in and/or cash-out agent networks. It serves unbanked populations effectively, allowing physical cash to be handed over in one location and picked up in another country within minutes. | | `PIS` | An open banking framework (heavily regulated under PSD2 in Europe) that allows licensed third-party providers to initiate a bank transfer directly from a consumer's bank account to a merchant. PIS ultimately triggers an underlying bank rail (like SEPA or Faster Payments) to move the money. | | `INTERNAL` | An internal transfer is a "book transfer" where money is moved between two accounts held at the exact same financial institution. Both the debtor and the creditor must be clients of the same bank. | | `CRYPTO` | The process of sending digital assets (like Bitcoin or Ethereum) from one blockchain wallet address to another. | | `CRYPTO_EXCHANGE` | An operation involving the trading of digital assets—either swapping fiat currency for crypto, or trading one cryptocurrency for another.CRYPTO\_EXCHANGE is treated the same as an INTERNAL operation. This means that both parties (DEBTOR and CREDITOR) must be customers of the financial institution. | | `FASTER_PAYMENTS` | The official real-time banking payment system in the UK. It facilitates near-instant money transfers between UK bank accounts. | You can always retrieve the full list of available operation types via [Classifier API](/api-reference/classifiers/operation-type). ## Financial Flow Direction Financial flow direction refers to the movement of money between entities or accounts. It dictates which party role must be a customer and helps to determine which direction is used for money. ### Incoming | Description | Party Role | Is Customer | Account Turnover Direction | | ----------------- | ------------------ | ----------- | -------------------------- | | Direct sender | DEBTOR | NO | OUT | | Direct receiver | CREDITOR | YES | IN | | Ultimate sender | ULTIMATE\_DEBTOR | YES/NO | OUT | | Ultimate receiver | ULTIMATE\_CREDITOR | YES/NO | IN | ### Outgoing | Description | Party Role | Is Customer | Account Turnover Direction | | ----------------- | ------------------ | ----------- | -------------------------- | | Direct sender | DEBTOR | YES | OUT | | Direct receiver | CREDITOR | NO | IN | | Ultimate sender | ULTIMATE\_DEBTOR | YES/NO | OUT | | Ultimate receiver | ULTIMATE\_CREDITOR | YES/NO | IN | ### Internal | Description | Party Role | Is Customer | Account Turnover Direction | | ----------------- | ------------------ | ----------- | -------------------------- | | Direct sender | DEBTOR | YES | OUT | | Direct receiver | CREDITOR | YES | IN | | Ultimate sender | ULTIMATE\_DEBTOR | YES/NO | OUT | | Ultimate receiver | ULTIMATE\_CREDITOR | YES/NO | IN | ## Flexible Fields While most operations share basic fields (like amount and currency), some require specific data to ensure accurate risk scoring: * **Card Operations:** Include merchant details, MCC codes, and terminal info. * **SEPA/SWIFT:** Focus on sender/receiver IBANs and intermediary bank details. If a field is not relevant to a specific operation type (for example, a merchant name for a SEPA transfer), you can simply leave it blank. ## Other Caveats If operation party does not contain currency, the currency is inherited from operation currency. Exception in `CRYPTO_EXCHANGE` where creditor does not inherit operation currency even if the currency is absent. # Risk Management Categories Source: https://api.amlyze.com/pages/risk_management_category A Guide to Customer and Operation Segmentation To effectively manage anti-money laundering (AML) risk, your institution's monitoring system must be adaptable to its unique business model, customer base, and product offerings.. A generic, one-size-fits-all approach is insufficient for the complexities of modern finance. Within the AMLYZE platform, the primary mechanism for achieving this tailored configuration is the **Risk Management Category**. This customizable attribute is a fundamental component present in both customer and transaction data payloads sent to the system. Its purpose is to enable granular segmentation, allowing allowing you to apply specific configurations across all major AML processes. This includes customer and transaction screening protocols, customer risk scoring models, real-time and retrospective transaction monitoring rule sets, and investigation workflows. It is important to distinguish the granular **Risk Management Category** from the higher-level **[Business Unit](/pages/business_unit)** concept. While both facilitate data and configuration separation, they operate at different architectural levels. A Business Unit creates a separation of entire datasets for distinct legal entities or operational environments, whereas a Risk Management Category enables nuanced segmentation *within* a single dataset. Different Business Units may share the same Risk Management Categories. | Feature | Business Unit | Risk Management Category | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Primary Purpose | Complete data segregation for distinct entities (e.g., different companies, tenants, jurisdictions). | Granular segmentation of customers and operations. | | Data Separation | Separates all customer, account, and transaction data, including alerts and cases. | Applies different rules and workflows to segments within the same dataset. | | Configuration Scope | Can have a different primary currency, timezone for monitoring, and user access controls. Can also be used to differentiate screening lists and sensitivity, applicable rules, individual rule settings, risk scoring logic, and investigation SLAs. | Differentiates screening lists and sensitivity, applicable rules, individual rule settings, risk scoring logic, and investigation SLAs. | | Typical Use Case | A multi-tenancy environment where different legal entities must have their data isolated.

A complex financial institution that segregates their clients and client transactions by business area. May or may not differentiate monitoring. | A single financial institution segmenting its B2C clients from its corporate clients for monitoring. | ## Customer Segmentation via Risk Management Category Effective AML compliance requires segmenting the customer base to apply controls that are proportionate to the risks each segment presents. The mechanism is straightforward: each customer profile submitted to AMLYZE is assigned a `riskManagementCategory`. This attribute acts as a key that links the customer to a specific, pre-configured set of rules and process configurations. By assigning different categories to different customer groups — such as individuals versus organizations, or standard retail users versus high-risk financial institutions — your AML team can ensure that the system's response is always aligned with the customer's risk profile. The specific AML controls that can be differentiated using the Customer Risk Management Category include: * **Targeted Rule Sets:** The customer category dictates which set of rules is applicable for key processes like Customer Risk Scoring and Retrospective Monitoring. This ensures that customers are evaluated against criteria relevant to their segment, preventing the misapplication of rules designed for a different type of customer. * **Different parameters and thresholds** within the same real-time or retrospective monitoring rules. * **Differentiated Screening Protocols:** The platform can apply different screening configurations based on the customer's category. This allows your AML team to control which watchlists (e.g., Sanctions, PEP, Adverse Media) are used for a particular segment and at what sensitivity level. For instance, a high-risk segment might be screened against more lists with a more sensitive matching algorithm than a standard-risk segment. * **Customized Investigation Workflows:** The category enables the tailoring of investigation processes for any alerts generated. This can include setting different Service Level Agreements (SLAs) for resolution, defining unique escalation paths, or assigning alerts from specific segments to specialized investigation teams. To illustrate, consider a financial institution that serves both individual consumers and other financial businesses. It could define two distinct categories: * **'Standard B2C User':** Customers in this category might be subject to standard sanctions and PEP screening. The Customer Risk Scoring rules applied would be tailored to typical retail behavior, and retrospective monitoring would focus on common consumer-level typologies. * **'High-Risk Financial Institution':** This category would trigger a more rigorous set of controls. Screening would be configured with higher sensitivity and include adverse media checks. The risk scoring and monitoring rules would be stricter, designed to detect complex corporate money laundering schemes, and any resulting alerts would have a shorter SLA for investigation. This same principle of granular control extends from the customer level down to each financial operation. ## Operation Segmentation via Risk Management Category Just as customers are segmented, it is strategically vital to segment financial transactions (operations) for monitoring. The Operation Risk Management Category provides the mechanism to apply this granular, transaction-level control. It supplements other already existing operation type filters: `operationType` (semi-configurable: allows adding additional external bank payment types) and `cardOperationSubType` (fully configurable). Every operation payload sent to AMLYZE for assessment includes a `riskManagementCategory`. This ensures that for every single payment, the system can apply a specific set of controls, rules, and outcomes on a per-transaction basis, rather than relying on a single, universal monitoring strategy. The key monitoring processes controlled by the Operation Risk Management Category are: * **Real-Time Monitoring Outcomes:** It allows the system to determine the automated outcome when a real-time monitoring rule is triggered. For example, the same rule logic (e.g., a high-value payment to a high-risk country) can be configured to produce different results based on the transaction's category. For one category, the outcome might be to 'stop' the payment for manual review. For another, the same trigger could result in an automatic 'reject' decision, preventing the payment from proceeding entirely. * **Monitoring Logic:** The system can use the operation's category to apply different sets of real-time monitoring rules. * **Payment and Transaction Type Differentiation:** The category is the most flexible method for creating custom classifications to differentiate monitoring for various payment types. It can be used as a filter in individual rules and supplements the `operationType` attribute which is less flexible and less customizable as it defines data validation rules within the AMLYZE API. ## Strategic Implementation and Best Practices Defining Risk Management Categories is a critical strategic exercise that forms the foundation of a successful AMLYZE integration. Thoughtful category design is not merely a technical task but a core business decision that ensures the AML program is both effective and efficient. A well-designed segmentation strategy transforms the AMLYZE platform from a generic tool into a customized AML solution that reflects your institution's specific risk appetite and operational logic. The responsibility for this design lies primarily with your AML team, who should analyze your institution's business processes, anticipate future needs, and weigh several key factors before settling on a category structure. ### Key Considerations for Defining Your Risk Management Categories * **Customer Base:** Differentiate between core customer segments that have distinct risk profiles, such as Individuals vs. Organizations or B2B vs. B2C models. * *Strategic Implication: Failure to segment the customer base correctly can lead to applying inappropriate monitoring models, such as using retail-focused rules for corporate customers, resulting in both missed risks and excessive false positives.* * **Products and Services:** Align categories with different product offerings that carry unique risk profiles. * *Strategic Implication: Failing to create distinct categories for high-risk products (e.g., crypto exchange services vs. standard payment acquiring) can lead to either overly restrictive controls on low-risk products or inadequate monitoring of high-risk activities, exposing your institution to significant regulatory and financial crime risk.* * **Payment Channels:** Create distinct categories for different payment methods (e.g., Regular SEPA vs. SEPA Instant) if they require different monitoring logic or real-time outcomes. No need to overdo: note that this may already be covered by `operationType`, use this only when operation type distinction is not sufficient or there are distinct real-time process needs. Otherwise, both Operation Category and Operation Type can be used as filters in individual rules. * **Workflow Requirements:** Define categories that map directly to required operational outcomes (e.g., Stop vs. Reject) or specialized investigation team responsibilities. * *Strategic Implication: Without categories tied to specific workflows, the system cannot reliably execute automated decisions like 'rejecting' a payment from a high-risk category versus 'stopping' one for review. This introduces operational risk and undermines your institution's ability to enforce its risk policy in real-time.* In summary, the Risk Management Category is the fundamental building block for tailoring the AMLYZE platform. By strategically defining categories for both customers and operations, you can precisely configure every aspect of your AML program: from screening sensitivity and rule application to investigation workflows and automated outcomes. This capability is what transforms the system into a solution that is perfectly aligned with your institution's specific risk appetite, business logic, and regulatory obligations. Categories are aligned during the initial onboarding process. Once established, any modifications or changes to these categories must be requested manually via Support. # Webhooks Source: https://api.amlyze.com/webhooks/webhook We use [Cloud Events (v1.0.2)](https://cloudevents.io/) standard to deliver information asynchronously via [HTTP Protocol Binding](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md) about requests made to the AMLYZE API. You can find more information about the Cloud Events specs in their [GitHub repository](https://github.com/cloudevents/spec). It is also possible to use one of the [official SDKs](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/SDK.md) to speed up integration with our system. ## Event Structure Events from AMLYZE are delivered using [Binary Content Mode](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#31-binary-content-mode). This means that identifications about object and event type are passed via HTTP header. Those headers, based on specification, have a `ce-` prefix. Passing information in such way, allows identifying information prior parsing the body, thus allowing more dynamic handling for the incoming events. ### Header Mapping | Cloud Event HTTP Header | Correlation With AMLYZE | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ce-id | Unique event ID. Unique per event. | | ce-source | Event Source. [RFC 3986 - Uniform Resource Identifier (URI)](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1). In most cases returns value from `communicationNumber`. | | ce-specversion | Cloud Events Specification version. Currently - `1.0`. | | ce-subject | Event subject, represents a resource's (customer, related entity, operation) external ID. | | ce-time | Event time. | | ce-type | Unique event type. | Here is an example of an event with headers: ``` ce-id: 019cd7cf-826c-731c-ba20-76f48d48ac9c ce-source: cef8654f-9885-4e61-b8e9-132b607ab6a4 ce-specversion: 1.0 ce-subject: dea0bcc0-52d2-4f82-bc46-6f87288939b5 ce-time: 2026-03-10t12:53:45.85z ce-type: app.amlyze.related_entity.screening.sanctions.pending content-length: 306 content-type: application/json { "customerExternalId": "78395a1c-272b-4263-ab9a-be5fe24055c5", "externalId": "dea0bcc0-52d2-4f82-bc46-6f87288939b5", "establishmentDate": "1998-04-07", "type": "ORGANIZATION", "title": "Sputnik", "nationalCode": "554555447884557", "relationCode": "OWNER", "countryCode": "RU", "screeningMatch": true, "screeningGuid": "20642e48-8251-47e3-a363-d857343ee171" } ``` ## Delivery Confirmation Your server should respond with a **2xx** status to acknowledge receipt of the webhook. All other status codes are treated as an **error** and their delivery is repeated.