Accounts API

Use the Account API to create and manage your Accounts.

Create an Account

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

Use this endpoint to create an Account or a Child-Account.

To create a Child-Account, you must set the identifier of the Parent Account in the "parentAccountId" field.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Request body

{
   "assetCode":"BRL",
   "name":"BRL deposit account", //optional, default = "{{asset}} {{type}} account"
   "alias":"conta1",
   "type":"deposit",
   "entityId":null, //optional, default = portfolios.entityId
   "parentAccountId":null, // optional, id of the parent 
   "productId":"aca9abcc-4dcd-454c-8ec1-b22df0e88795", // optional
   "status":{
      "code":"c346fed3-e915-4a19-b9fb-f63114a3e76b",
      "description":"Random description to describe the code",
      "allowSending":true,
      "allowReceiving":true
   },
   "metadata":{
      "country":"japan"
   }
}

Response codes

201

{
   "id":"776c4fcd-62dc-4aaa-842c-6bbcbe35ed76",
   "entityId":"1b8037e8-459d-4bf4-a1f9-0d075b500910",
   "ledgetId":"77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
   "organizationId":"5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
   "parentAccountId":"e911b785-fe21-4bba-b211-ce200cd4cbc9",
   "productId":"aca9abcc-4dcd-454c-8ec1-b22df0e88795",
   "name":"BRL deposit account",
   "status":{
      "code":"c346fed3-e915-4a19-b9fb-f63114a3e76b",
      "description":"Random description to describe the code",
      "allowSending":true,
      "allowReceiving":true
   },
   "alias":"conta1",
   "assetCode":"BRL",
   "type":"deposit",
   "balance":{
      "available":25,
      "onHold":2,
      "scale":2
   },
   "metadata":{
      "country":"japan"
   },
   "createdAt":"2024-02-08T16:59:31+0300",
   "updatedAt":"2024-02-08T16:59:31+0300",
   "deletedAt":null
}

400

{
   "code":"0020",
   "title":"Alias Unavailability Error",
   "message":"The alias {{alias}} is already in use. Please choose a different alias and try again."
}

400

{
   "code":"0029",
   "title":"Invalid Parent Account ID",
   "message":"The specified parent account ID does not exist. Please verify the ID is correct and try your request again."
}

400

{
   "code":"0030",
   "title":"Mismatched Asset Code",
   "message":"The parent account ID you provided is associated with a different asset code than the one specified in your request. Please make sure the asset code matches that of the parent account, or use a different parent account ID and try again."
}

400

{
   "code":"0034",
   "title":"Asset Code Not Found",
   "message":"The provided asset code does not exist in our records. Please verify the asset code and try again."
}

400

{
   "code":"0035",
   "title":"Portfolio ID Not Found",
   "message":"The provided portfolio ID does not exist in our records. Please verify the portfolio ID and try again."
}

400

{
   "code":"0036",
   "title":"Product ID Not Found",
   "message":"The provided product ID does not exist in our records. Please verify the product ID and try again."
}

404

{
   "code":"0037",
   "title":"Ledger ID Not Found",
   "message":"The provided ledger ID does not exist in our records. Please verify the ledger ID and try again."
}

404

{
   "code":"0038",
   "title":"Organization ID Not Found",
   "message":"The provided organization ID does not exist in our records. Please verify the organization ID and try again."
}

---

Retrieve all Accounts

GET /v1/organizations/{{id}}/ledgers/{{id}}/portfolio/{{id}}/accounts

Use this endpoint to retrieve the information about all Accounts in the Portfolio.

Headers

Name	Value
Authorization	Bearer <token>

Query parameters

Name	Type	Description
type	String	The account type.
assetCode	String	The code of the asset.

Response codes

201

[
  {
    "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": "satoshi",
    "status": {
      "code": "ACTIVE",
      "description": "AML", 
      "allowSending": true,
      "allowReceiving": true
    },
    "assetCode": "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",
    "assetCode": "BRL",
    "productId": null,
    "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "BRL deposit account",
    "alias": "conta1",
    "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",
    "assetCode": "BRL",
    "productId": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
    "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "BRL savings account",
    "alias": "conta2",
    "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
  }
]

400

{
   "code":"0030",
   "title":"Mismatched Asset Code",
   "message":"The parent account ID you provided is associated with a different asset code than the one specified in your request. Please make sure the asset code matches that of the parent account, or use a different parent account ID and try again."
}

---

Retrieve Account by id

GET /v1/organizations/{{id}}/ledgers/{{id}}/portfolio/{{id}}/accounts/{{id}}

Use this endpoint to retrieve the information of a specific Account (or child-account).

Headers

Name	Value
Authorization	Bearer <token>

Response codes

200

{
  "id": "68d2cd27-5a2f-4e4d-824a-96c7d52f99df",
  "assetCode": "BRL",
  "entityId": "ab3a5146-e97c-46e9-aaab-4cfb78178d55",
  "productId": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
  "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "name": "BRL savings account",
  "alias": "conta2",
  "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
}

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}

---

Update an Account

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

Use this endpoint to edit and update the information of a specific Account. When you update an Account, the following fields can be edited:

• name

• status

• alias

• entityId

• allowSending

• allowReceiving

• productId

• metadata

When updating the metadata object, all previous key-value pairs must be included in the update, or they will be removed. Check the Metadata section for more information.

The following account types can be updated: deposit, savings, loans, overdrafts, market place, and credit card.

In the Open Source contracting model, all accounts can be edited

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Request body

{
  "name": "The BTC main account",
  "alias": "satoshi",
  "status":{
    "code": "ACTIVE",
    "description": null, 
    "allowSending": false,
    "allowReceiving": false
  },
  "entityId": "fa26e62e-b9a2-4779-ae1c-c0e7aca773c",
  "productId": null
}

Response codes

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": null,
    "alias": "satoshi",
    "status":{
      "code": "ACTIVE",
      "description": null, 
      "allowSending": false,
      "allowReceiving": false
    },
    "assetCode": "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
}

400

{
   "code":"0020",
   "title":"Alias Unavailability Error",
   "message":"The alias {{alias}} is already in use. Please choose a different alias and try again."
}

---

Delete an Account

DELETE /v1/organizations/{{id}}/ledgers/{{id}}/portfolio/{{id}}/accounts/{{id}}

Use this endpoint to deactivate a specific Account.

The following account types can be deactivated: deposit, savings, loans, overdrafts, market place, and credit card.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Response codes

204

400

{
   "code":"0012",
   "title":"Account Balance Deletion Error",
   "message":"An account or sub-account cannot be deleted if it has a remaining balance. Please ensure all remaining balances are transferred to another account before attempting to delete."
}

404

{
   "code":"0007",
   "title":"Entity Not Found",
   "message":"No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage."
}