TABLE OF CONTENTS

Introduction


This article will you walk you through helpful information for integration with the Source by First AML platform through the Public API.


API Documentation 


The First AML Public API documentation can be found here.


This web resource has all information required to integrate with our platform.


Helpful notes: 

  • All values are case-sensitive. Please ensure you use the exact casing (upper or lower case) as shown on the website.

  • FAML distinguishes between individuals and entities. Each new individual or entity is assigned a unique ID. This ID must be included in every request related to an existing client to avoid creating duplicate records.
    You may use the     CaseReference field to pass your CRM/PMS ID, allowing you to link cases back to your internal system.

  • OfficeId and OrganisationId must be included in all requests. Please see here how to get the IDs (via tokens).


Please ensure that your companies and organisations are mapped to our supported Entity Types.


Where to start with Case Creation


  1. CreateCaseForIndividualsInput
  • Mandatory
    • individuals - The type of verification applicable to this case
      • emailAddress (recommended)
      • isCaseContact (recommended)
      • needsVerification 
      • phoneNumber (recommended
      • preferredName 
    • initialState - The state of the case after creation
    • officeId - Unique ID of the Office to add the case to. If this organization has one or more associated offices, then the office is required
    • organizationId - Unique ID of the Organization to add the case to
  • Recommended
    • assignedUsers - The users to assign to the case
    • lead - The contact details of the person leading the case
    • reference - Client-assigned reference for this case. Can be set to null to clear the reference value
    • requestor - The contact details of the person requesting the case


  1. CreateCaseForEntitiesInput
  • Mandatory
    • entities - The entities requiring verification in this case
      • identifier (recommended) = Registration Number
      • registeredCountry (recommended)
      • registrationAuthorityCode (recommended)
      • tradingName 
      • Type 
    • individuals - The type of verification applicable to this case
      • emailAddress (recommended)
      • isCaseContact (recommended)
      • needsVerification 
      • phoneNumber (recommended
      • preferredName 
    • initialState - The state of the case after creation
    • officeId - Unique ID of the Office to add the case to. If this organization has one or more associated offices, then the office is required
    • organizationId - Unique ID of the Organization to add the case to
  • Recommended
    • assignedUsers - The users to assign to the case
    • lead - The contact details of the person leading the case
    • reference - Client-assigned reference for this case. Can be set to null to clear the reference valueYup
    • requestor - The contact details of the person requesting the case


The fields that we have flagged as "recommended" are not mandatory when creating a case via the API. However, they are useful in order to progress the case once it is created.For example, the email address is not required but is helpful to include when creating a case via the API. If you would like to leverage the automation to automatically send the identity verification form to an individual, an email address would be helpful to ensure the automation can run.


Other important things to consider

  • Webhooks

A webhook is triggered whenever a case transitions between the following statuses: In Progress, Ready to Review, and Complete.
Note that, for security reasons, the webhook events do not contain case details; you will need to query the API to retrieve case information after receiving a webhook event.

Please provide api@firstaml.com with the endpoint URL for your Sandbox webhook (and later the Production webhook), along with the list of events you want to subscribe to. The most commonly used event is CaseStatusUpdated. Our engineering team will supply an HMAC verification key.

  • Statuses Checks

The caseStatus field represents the case’s position within the workflow only; it does not reflect any AML decision.

For individuals, refer to the “overall” field within individualVerificationStatus to understand the AML team’s decision.

For entities, use the equivalent overall field in entityVerificationStatus.

Both objects also include detailed results of specific checks (e.g., PEP, sanctions, address), if required.

  • Risk Assessment

We currently support synchronizing case-level risk assessments (HIGH, MEDIUM, LOW) from your system to FirstAML. Numeric risk scoring is not supported at this stage.
 You can use the Risk Submission mutation to retrieve answers from the FirstAML assessment via the API once available.

To speed up testing, we recommend using our preconfigured Insomnia templates for quick setup and sample requests. A step-by-step guide is available HERE.

  • Testing

If you want to test with dummy entities, you can use our sample Australian companies in your Sandbox environment:

  • Company Number 13108008 - Urban Fabric Developments Pty Ltd 

    • Private company with 1 x directors and 2 x shareholders, 1 layer of shareholding

  • Company Number 644539668 - Osass Australia Pty Ltd 

    • Private company with 3 x directors and 3 x shareholders

  • Company Number 644219063 - Developer 8 Pty Ltd 

    • Private company with 1 x directors and 3 x layers of shareholding. There is a trust in shareholding with 1 x trustee company.

  • Company Number 658107263 - The Green Tasmania Pty Ltd

    • Private company with 2 x directors, 3 x layers of shareholding in 2 x shareholding branches. There is a trust in shareholding with 1 x trustee company.

Details on Individual Forced Verifications are available HERE.