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

{
  "instrumentCode": "BRL",
  "alias": "gabriel",
  "name": "My BRL account",
  "type": "deposit",
  "entityId": "1b8037e8-459d-4bf4-a1f9-0d075b500910",
  "parentAccountId": "e911b785-fe21-4bba-b211-ce200cd4cbc9",
  "productId": "aca9abcc-4dcd-454c-8ec1-b22df0e88795",
  "status": {
    "code": "c346fed3-e915-4a19-b9fb-f63114a3e76b",
    "description": "Random description to describe the code"
  },
  "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": "My BRL account",
  "status": {
    "code": "c346fed3-e915-4a19-b9fb-f63114a3e76b",
    "description": "Random description to describe the code"
  },
  "allowSending": true,
  "allowReceiving": true,
  "alias": "gabriel",
  "instrumentCode": "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": "0030",
  "title": "Mismatched Instrument Code",
  "description": "The provided parent account ID is associated with a different instrument code than the one specified in your request. Please ensure the instrument code matches that of the parent account, or use a different parent account ID and try again."
}

400

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

400

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

400

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

404

{
  "code": "0037",
  "title": "Ledger ID Not Found",
  "description": "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",
  "description": "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.
instrumentCode	String	The code of the instrument.

Request body

{
  "instrumentCode": "BRL",
  "alias": "gabriel",
  "name": "My BRL account",
  "type": "deposit",
  "parentAccountId": "e911b785-fe21-4bba-b211-ce200cd4cbc9",
  "productId": "aca9abcc-4dcd-454c-8ec1-b22df0e88795"
}

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": "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": null,
    "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
  }
]

400

{
  "code": "0030",
  "title": "Mismatched Instrument Code",
  "description": "The provided parent account ID is associated with a different instrument code than the one specified in your request. Please ensure the instrument code matches that of the parent account, or use a different parent account ID and try again."
}

404

{
  "code": "w-0001",
  "title": "Mismatched Instrument Code",
  "message": "Invalid data provided"
}

---

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",
  "instrumentCode": "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": "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
}

404

{
  "code": "0007",
  "title": "Invalid Script Error",
  "description": "Entity not found."
}

---

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
  },
  "entityId": "fa26e62e-b9a2-4779-ae1c-c0e7aca773c9",
  "allowSending": false,
  "allowReceiving": false,
  "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,
    "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
}

400

{
  "code": "0020",
  "title": "Alias has been taken",
  "description": "The alias {{alias}} has been taken already. Please, inform another one."
}

---

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": "Balance remaining"
  "description": "You cannot delete an account or a child account if there is balance remaining. Transfer all the balance to another account and try it again."
}

404

{
  "code": "0007",
  "message": "Entity not found."
}