Clustering customers

You can use the Products API to create specific clusters for your customers. This is commonly used when you want to allocate your customers into different tiers, such as:

• Standard: Customers who have just registered on the platform.

• Gold: Customers who have had an account for at least one year or spend more than $5,000 per month.

• VIP: Customers with over $1M invested in the app.

To do this, call the Create a Product endpoint with the following example payload:

POST /v1/organizations/{{id}}/ledgers/{{id}}/products

Body:

{
  "name": "Gold",
  "status": {
    "code": "001",
    "description": "Ready to use"
  },
  "metadata": {
    "monthlyExpenses": 5000,
    "minumumYears" 1
  }
}

201:

{
  "id": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
  "ledgerId": "44d5e310-5caa-4d51-812f-2d56c1bbcacd",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "name": "Gold",
  "status": {
    "code": "001",
    "description": "Ready to use"
  },
  "metadata": {
    "monthlyExpenses": 5000,
    "minumumYearsAsACustomer" 1
  },
  "createdAt": "2024-01-29T00:12:00+0300",
  "updatedAt": "2024-01-29T00:12:00+0300",
  "deletedAt": null
}

After that, accounts that meet these requirements can have their productId updated using the Update an Account endpoint with the following payload.

PATCH /v1/organizations/{{id}}/ledgers/{{id}}/portfolios/{{id}}/accounts/{{id}}

Body:

{
  "productId": "aca9abcc-4dcd-454c-8ec1-b22df0e88795"
}

200:

{
    "id": "776c4fcd-62dc-4aaa-842c-6bbcbe35ed76",
    "entityId": "fa26e62e-b9a2-4779-ae1c-c0e7aca773c9",
    "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "The BTC main account",
    "productId": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
    "alias": "satoshi",
    "status":{
      "code": "ACTIVE",
      "description": null
    },
    "allowSending": false,
    "allowReceiving": false,
    "instrumentCode": "BTC",
    "type": "deposit",
    "balance": {
      "available": 25,
      "onHold": 2,
      "scale": 2
    },
    "metadata": null,
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
}

After that, you can retrieve all customers with this productId using the Retrieve all Accounts endpoint.

GET /v1/organizations/{{id}}/ledgers/{{id}}/accounts?productId=aca9abcc-4dcd-454c-8ec1-b22df0e88795

200:

[
  {
    "id": "776c4fcd-62dc-4aaa-842c-6bbcbe35ed76",
    "name": "BTC account",
    "entityId": "ab3a5146-e97c-46e9-aaab-4cfb78178d55",
    "productId": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
    "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "alias": "satoshi100m",
    "status": {
      "code": "ACTIVE",
      "description": "AML"
    },
    "allowSending": true,
    "allowReceiving": true,
    "instrumentCode": "BTC",
    "type": "deposit",
    "balance": {
      "available": 25,
      "onHold": 2,
      "scale": 2
    },
    "metadata": null,
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
  },
  {
    "id": "e911b785-fe21-4bba-b211-ce200cd4cbc9",
    "instrumentCode": "BRL",
    "productId": "ab3a5146-e97c-46e9-aaab-4cfb78178d55",
    "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "My BRL account",
    "alias": "santos-dumont",
    "status": {
      "code": "ACTIVE",
      "description": "AML"
    },
    "allowSending": true,
    "allowReceiving": true,
    "type": "deposit",
    "balance": {
      "available": 2321231,
      "onHold": 11231,
      "scale": 2
    },
    "metadata": null,
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
  },
  {
    "id": "68d2cd27-5a2f-4e4d-824a-96c7d52f99df",
    "instrumentCode": "BRL",
    "productId": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
    "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "My BRL account",
    "alias": "gabe",
    "status": {
      "code": "ACTIVE",
      "description": "AML"
    },
    "allowSending": true,
    "allowReceiving": true,
    "type": "savings",
    "balance": {
      "available": 2321231,
      "onHold": 11231,
      "scale": 2
    },
    "metadata": {
      "mrOlympia": "Ronnie Coleman"
    },
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
  }
]