Customer Portal

Managees

Overview

The Managees module provides a set of API endpoints designed for managers to onboard and manage their linked managees within the platform. The endpoints facilitate various operations, from creating managee profiles to listing all managees and generating widget user references for enhanced user interaction with the platform's widgets.

API Endpoints for the Managees Module:

  1. Create Managee: This endpoint is used by managers to create a new customer profile for a personal customer. The user also inputs additional data necessary for KYC screening.

  2. List Managees: Managers can use this endpoint to retrieve a list of all managees they have created. The list provides essential information about each managee, such as their ID, name, date added, verification status, and any associated widget references. This is a GET request with pagination capabilities to effectively manage large numbers of managees.

  3. Get List of Accounts for a Managee by ID: (DEPRECATED) Retrieves a list of accounts belonging to a managee. You can filter the list by the managee's ID, the asset (currency), and control pagination with page number and size.

  4. Create Widget User: This POST endpoint enables managers to create a widget user reference for their managees, which facilitates the managee's interaction with the platform's widgets. A widget user reference is associated with the managee, allowing for a more dynamic and engaging user experience within the platform interface.

These API calls are integral to managee account management as they allow for seamless operations concerning the create-list-manage lifecycle of managee profiles under a manager account. Through their use, managers can streamline operations, ensure account accuracy, and deliver a more refined platform experience to their managees.

Create a Managee

Allows a manager to create a linked customer, referred to as a managee. The user provides additional information necessary for KYC screening. A file with proof of address is also required. The response contains a Jumio Link, from which the customer can enter and verify their identity information. A manager can set up a new customer account under their purview by entering the customer's (managee's) details into the system.

  • Endpoint: /api/v4/customer/managees/create

  • Method: POST

  • Request Body:

    • emailAddress (String, max length: 200): The email address of the new managee.

    • manageesReference (String, max length: 100): A unique reference to identify the managee.

    • fiatCurrencyCode (String, max length: 10): The fiat currency code for the managee's account (e.g., USD). Currently only "USD" is supported.

    • fullName (String, max length: 200): The managee's full legal name.

    • firstGivenName (String, max length: 100): The managee's first given name.

    • lastSurname (String, max length: 100): The managee's last surname, if the user has multiple surnames.

    • addressLine1 (String, max length: 200): The street address or equivalent for the managee.

    • addressLine2 (String, max length: 200, optional): Additional address information if necessary.

    • townCity (String, max length: 100): The town or city of the managee's address.

    • stateProvince (String, max length: 1000): The state, province, or equivalent area of the address.

    • postcode (String, max length: 50): The postcode or ZIP code associated with the managee's address.

    • addressCountryISO (String, max length: 3): The ISO country code of the managee's address.

    • phoneNumber (String, max length: 100): The managee's phone number.

    • dateOfBirth (String, ISO 8061): The managee's date of birth in "YYYY-MM-DD" format.

    • taxNumber (String, max length: 100): The managee's tax identification number.

    • nationalityISO (String, max length: 3): The ISO country code of the managee's nationality.

    • sourceFundsTypes (String Array): Source of Funds, with values from this table.

    • estimatedNetWorth (Decimal): Managee's estimated net worth (USD).

    • estimatedGrossAnnualIncome (Decimal): Managee's estimated gross annual income (USD).

    • otherBanks (String Array): Other banks at which managee has accounts.

    • bActivelyEmployed (Boolean): Is the managee actively employed.

    • employedCompanyName (String, max length: 200): Full name of managee's company.

    • employedJobTitle (String, max length: 200): Managee's job title.

    • purposeOfOpeningAccountTypes(String Array): Purpose of opening account, with values from this table.

    • monthlyTurnover(Decimal): Managee's monthly turnover (USD).

    • anticipatedTransactionActivity(Decimal): Managee's Anticipated transaction activity for the next 12 months (USD).

    • purchaseCryptoMonthlyVolume(Decimal): Managee's Purchasing Crypto - Monthly Volume.

    • purchaseCryptoAverageAmount(Decimal): Managee's Purchasing Crypto - Average Amount (USD).

    • purchaseCryptoTotalAmountPerMonth(Decimal): Managee's Purchasing Crypto - Total Amount Monthly (USD).

    • sellingCryptoMonthlyVolume(Decimal): Managee's Selling Crypto - Monthly Volume.

    • sellingCryptoAverageAmount(Decimal): Managee's Selling Crypto - Average Amount (USD).

    • sellingCryptoTotalAmountPerMonth(Decimal): Managee's Selling Crypto - Total Amount Monthly (USD).

    • totalMonthlyVolume (Decimal): Managee's Total for All Monthly Volume.

    • totalAverageAmount (Decimal): Managee's Total for All Average Amount (USD).

    • totalMonthlyAmount (Decimal): Managee's Total Amount Per Month (USD).

    • btcTradingPercentage (Decimal): Managee's Percentage (%) of Anticipated Trading Activity by Coin - BTC.

    • ethTradingPercentage (Decimal): Managee's Percentage (%) of Anticipated Trading Activity by Coin - ETH.

    • usdcTradingPercentage (Decimal): Managee's Percentage (%) of Anticipated Trading Activity by Coin - USDC.

    • otherCoinsTradingPercentage (Decimal): Managee's Percentage (%) of Anticipated Trading Activity by Coin - Other Coins.

    • bIrsTax (Boolean): Managee's agreement with "I confirm that I am personally up to date and compliant with IRS tax filing requirements".

    • bForeignAccountTax(Boolean): Managee's agreement with "I confirm that I am in full compliance with Foreign Account Tax Compliance Act (FACTA)".

    • bNotCriminal(Boolean): Managee's agreement with "I declare I have not been engaged in or have benefited from criminal conduct in any part of the world and funds which are subject to the proposed arrangement do not wholly or in part directly represent the proceeds of criminal conduct".

    • bAccurateInfo(Boolean): Managee's agreement with "I declare that the information given hereunder and in the documents requested hereby is to the best of your knowledge true and accurate as at the date hereof,and should there be any changes in the information so provided you undertake to promptly advise our law firm of the same in writing".

    • ProofOfAddressFile (String): Managee's proof of address file. Base 64 encoded JPEG or PNG data.

    • ProofOfAddressType (String): Type of proof of address file. Possible values: BankStatement, CouncilBill, CreditCardStatement, LeaseAgreement, LoanApplication, MortgageApplication, PhoneBill, TaxReturn, UtilityBill.

Source of Funds Types

Value
Description

Salary

Salary

Savings

Savings

SelfEmployed

Self Employed

Loans

Loans/Borrowed Funds

Purpose Of Opening Account Types

Value
Description

DigitalAsset

Digital Asset OTC Desk

CryptoLoans

Crypto Loans

PeerToPeer

Peer to Peer Transfer

CreditDebit

Credit or Debit Services

Request Body Example

{
  "emailAddress": "test-email-v4@avamae.co.uk",
  "manageesReference": "34233rqcpomrkvr3g56",
  "fiatCurrencyCode": "USD",
  "fullName": "Alan Nameson",
  "firstGivenName": "Alan",
  "lastSurname": "Nameson",
  "townCity": "Hometown",
  "addressCountryISO": "USA",
  "addressLine1": "House Name",
  "stateProvince": "Ohio",
  "postcode": "12345-1234",
  "phoneNumber": "+447729594017",
  "dateOfBirth": "1994-01-02",
  "taxNumber": "200000025",
  "nationalityISO": "USA",
  "occupation": "Worker",
  "sendInvite":false,
  "SourceFundsTypes": ["Salary", "Savings", "Loans"],
  "OtherSourceOfFunds": null,
  "EstimatedNetWorth": 100000,
  "EstimatedGrossAnnualIncome": 80000,
  "OtherBanks": ["Bank1", "Bank2"],
  "bActivelyEmployed": true,
  "EmployedCompanyName": "ABC Company",
  "EmployedJobTitle": "Software Engineer",
  "PurposeOfOpeningAccountTypes": ["DigitalAsset"],
  "MonthlyTurnover": 50000,
  "AnticipatedTransactionActivity": 2000,
  "PurchaseCryptoMonthlyVolume": 10000,
  "PurchaseCryptoAverageAmount": 500,
  "PurchaseCryptoTotalAmountPerMonth": 15000,
  "SellingCryptoAverageAmount": 450,
  "SellingCryptoMonthlyVolume": 8000,
  "SellingCryptoTotalAmountPerMonth": 12000,
  "TotalMonthlyVolume": 18000,
  "TotalAverageAmount": 475,
  "TotalMonthlyAmount": 13000,
  "BtcTradingPercentage": 50,
  "EthTradingPercentage": 30,
  "UsdcTradingPercentage": 10,
  "OtherCoinsTradingPercentage": 10,
  "bIrsTax": true,
  "bForeignAccountTax": true,
  "bNotCriminal": true,
  "bAccurateInfo": true,
  "proofOfAddressFile": "/9j/4AAQSkZJRgABAQEAYABgAAD/4QAiRXhpZg...Zpdn/9k=",
  "proofOfAddressType": "UtilityBill"
}

Response Element Types:

  • id (Integer): Reference ID, not used here.

  • details (Object)

    • manageesId (Integer): Newly created managee's ID, used to identify the user in other API requests.

    • jumioLink (Integer): Link for customer to complete identity verification process.

  • status (String): "1" for success, "0" for error.

  • errors (Array): List of errors, if any.

Success Response Example:

{
    "id": 0,
    "details": {
        "manageesId": 14083,
        "jumioLink": "https://customer.ibanera.com/manageesidverification?token=nHK5gM%2fGCJKBcSsAG8GkUg%3d%3d"
    },
    "status": "1",
    "errors": []
}

Possible Error Message Codes

Error Message Code Example
Description

Required

Named field missing

Invalid_Length

Named field length invalid

Invalid_Format

Named field format invalid

Username_Not_Available

User with requested email already exists

Currency_Invalid

Currency not supported

Nationality_Invalid

Requested user nationality not supported

Address_Country_Invalid

Address country not supported

Percentage_Invalid

Percentages must be between 0 and 100

Total_Percentage_Invalid

Total percentage must be at most 100

Type_Duplicated

Duplicate entries in array

IrsTax_Invalid

User must agree to terms

ForeignAccountTax_Invalid

User must agree to terms

NotCriminal_Invalid

User must agree to terms

AccurateInfo_Invalid

User must agree to terms

List Managees

Retrieve a paginated list of basic data for all managees linked to the manager. Managers can view a list of all their linked customers, sortable and navigable through numerous pages.

  • Endpoint: /api/v1/customer/managees/list

  • Method: GET

Query Parameters:

  • PageNumber: Page to view

  • PageSize: Results per page

Success Response Parameters:

  • id (Integer): An identifier for the list operation; might not be used in the response.

  • details (Array of Objects): An array containing managee objects with the following structure:

    • manageesId (Integer): The unique ID of the managee user.

    • manageesReference (String): Your reference for the managee.

    • name (String): Managee’s full name.

    • addDate (DateTime): Date and time when the managee was created, formatted in ISO 8601.

    • verificationStatus (String): Current verification status of the managee ("Pending," "Accepted," or "Rejected").

    • widgetUserReference (String): Widget user reference associated with the managee, if any.

  • pageSize (Integer): The number of results per page returned in the response.

  • pageNumber (Integer): The current page number in the paginated list.

  • numberOfPages (Integer): The total number of available pages.

  • status (String): Indicates the status code of the response ("1" for success).

  • errors (Array): Contains error details if any occurred during the request.

Response Body Example:

{
    "id": 11108,
    "details": [
        {
                "manageesId": 11096,
                "manageesReference": "34233rqcpomrkvre",
                "name": "Alan Nameson",
                "addDate": "2022-10-03T10:59:04.213",
                "verificationStatus": "Pending",
                "widgetUserReference": "widgetReference"
        } 
    ],
    "pageSize": 15,
    "pageNumber": 1,
    "numberOfPages": 1,
    "status": "1",
    "errors": []
}

Response with Errors Parameters:

  • id (Integer): Reference identifier for the request; often not used with errors.

  • details (null): Typically null when errors are present.

  • status (String): Status code of the operation ("0" for errors).

  • errors (Array of Objects): An array of error objects, each containing:

    • fieldName (String): The field name that caused the error.

    • messageCode (String): Specific code indicating the error (e.g., "Invalid").

Possible Error Message Codes

Error Message Code Example
Description

Invalid

Named parameter invalid

Get List of Accounts for a Managee by ID

This endpoint is deprecated and may have functionality issues. This endpoint was replaced by the new List Asset Accounts for Customer endpoint (Accounts Module API). Please use List Asset Accounts for Customer for this purpose.

This endpoint retrieves a list of accounts belonging to a managee. You can filter the list by the managee's ID, the asset (currency), and control pagination with page number and size. This functionality is like a filterable list that shows all the accounts for individuals or entities managed by another party. It allows the user to see only specific accounts, sort it by the type of money in the account (like USD), and break the list into readable chunks (pages).

  • Endpoint: /api/v1/customer/manageeaccounts/list

  • Method: GET

  • Query Parameters:

    • ManageesId (Integer): Managee's ID for filtering (optional).

    • Asset (String): Asset code for filtering (optional).

    • PageNumber (Integer): The page number for pagination, default is 1 (optional).

    • PageSize (Integer): The number of records per page, default is 10 (optional).\

Response Body Parameters and Types:

  • id (Integer): A reference ID for the account list.

  • details (Array of Objects): A list of account objects, each with the following structure:

    • id (Integer): The unique ID for the account.

    • manageesId (Integer): The related managee’s ID for this account.

    • name (String): The name associated with the account.

    • routingNumber (String): The account routing number for financial transactions.

    • accountNumber (String): The specific account number.

    • asset (String): Currency code of the account’s asset.

    • totalBalance (Decimal): The total money held in the account.

    • availableBalance (Decimal): The funds available for withdrawal or spending.

    • pendingBalance (Decimal): Amounts that are in the process of being deposited or withdrawn.

    • bSuppressed (Boolean): Indicates whether the account is currently suppressed (hidden) or active.

    • dateAdded (String): Date and time the account was created, in ISO 8601 format.

  • pageSize (Integer): Numerical size of the current page in the paginated response.

  • pageNumber (Integer): Current page number within the paginated set.

  • numberOfPages (Integer): Total number of response pages available.

  • status (String): The operation's success status; '1' for success.

  • errors (Array): An array of error objects, detailing any issues encountered with the request.

Success Response Example:

The response returns a list of managee accounts with details including the account's name, routing number, account number, asset, balances, and addition date.

{
  "id": 1025,
  "details": [
    {
      "id": 1055,
      "manageesId": 1004,
      "name": "Account Name",
      "routingNumber": "021214891",
      "accountNumber": "357901009807",
      "asset": "USD",
      "totalBalance": 100.0,
      "availableBalance": 0.0,
      "pendingBalance": 100.0,
      "bSuppressed": false,
      "dateAdded": "2022-07-07T16:33:08.413+00:00"
    }
  ],
  "pageSize": 10,
  "pageNumber": 1,
  "numberOfPages": 1,
  "status": "1",
  "errors": []
}

Create Widget User

This endpoint allows the creation of a widget user reference for the managee to facilitate the use of the crypto widget. Special identifiers for managees are generated to give them access to easier checkouts, as customer information will already be provided.

  • Endpoint: /api/v1/customer/managees/createwidgetuser

  • Method: POST

Request Body:

  • manageesId (Integer): The managee's ID for who the widget user is being created.

  • widgetUserReference (String, max length 100): The widget user reference associated with the managee.

Success Response Parameters:

  • id (Integer): A reference ID for the createwidgetuser operation, not typically used in the response.

  • status (String): The status code of the operation ("1" for success).

  • errors (Array): An empty array, indicating that no errors occurred during the request.

Success Response Example:

{
  "id": 0,
  "status": "1"
  "errors": []
}

Response Example with Errors:

{
  "id": 0,
  "details": null,
  "status": "0",
  "errors": [
    {
      "fieldName": "ManageesId",
      "messageCode": "Managee_Not_Found"
    }
  ]
}

Possible Error Message Codes

Error Message Code Example
Description

Widget_Client_Not_Found

Manager does not have associated widget client

Managee_Not_Found

Managee’s Id is invalid

Managee_Not_Verified

Managee is not verified

Widget_User_Already_Exists

Managee already has an associated widget user

Already_Used

WidgetUserReference already used before

PreviousTransaction CancellationNextInformation Requests (RFIs)

Last updated