# Manage accounts with the API

Use this page for account operations with the Ripple Custody API. For UI procedures, see [Manage accounts in the UI](/products/custody/accounts-and-assets/accounts/manage-accounts-ui). For the account model, see [Accounts](/products/custody/accounts-and-assets/accounts/overview).

## Account actions

| Action | API procedure | API reference |
|  --- | --- | --- |
| Create an account | [Create an account with the API](#create-an-account-with-the-api) | [Propose an intent](/products/custody/reference/api/openapi/intents/createintent), [Perform a dry run](/products/custody/reference/api/openapi/intents/intentdryrun) |
| View account details | [View account details](#view-account-details) | [List accounts](/products/custody/reference/api/openapi/accounts/getaccounts), [Get account details](/products/custody/reference/api/openapi/accounts/getaccount), [Retrieve account address](/products/custody/reference/api/openapi/accounts/getaccountaddress) |
| Update account details | [Update account details](#update-account-details) | [Propose an intent](/products/custody/reference/api/openapi/intents/createintent), [Perform a dry run](/products/custody/reference/api/openapi/intents/intentdryrun) |
| Add ledgers to an account | [Add ledgers to an account](#add-ledgers-to-an-account) | [Propose an intent](/products/custody/reference/api/openapi/intents/createintent), [Perform a dry run](/products/custody/reference/api/openapi/intents/intentdryrun) |
| Lock or unlock an account | [Lock or unlock an account](#lock-or-unlock-an-account) | [Propose an intent](/products/custody/reference/api/openapi/intents/createintent), [Perform a dry run](/products/custody/reference/api/openapi/intents/intentdryrun) |
| Check account balances | [Check account balances](#check-account-balances) | [Get account balances](/products/custody/reference/api/openapi/accounts/getaccountbalances) |
| Force an account balance update | [Force an account balance update](#force-an-account-balance-update) | [Update account balances forcefully](/products/custody/reference/api/openapi/accounts/forceupdateaccountbalances) |
| Configure compliance settings | [Configure compliance settings](#configure-compliance-settings) | [Get compliance configuration](/products/custody/reference/api/openapi/accounts/getcomplianceconfiguration), [Set compliance configuration](/products/custody/reference/api/openapi/accounts/upsertcomplianceconfiguration), [List compliance configurations](/products/custody/reference/api/openapi/accounts/listcomplianceconfigurations) |


Account changes use the standard intent flow. For signing, approval, and status checks, see [Manage intents and approvals](/products/custody/governance/intents/manage-intents-and-approvals), [Sign intents](/products/custody/identity-and-access/authentication/authenticate-api-requests#signing-intents-state-mutation-operations), and [Check updates](/products/custody/governance/intents/manage-intents-and-approvals#check-state-with-the-api).

## Common operations

| Operation | Intent type | Use when |
|  --- | --- | --- |
| Create account | `v0_CreateAccount` | Register a new account for one or more ledgers. |
| Update account | `v0_UpdateAccount` | Change mutable account details such as alias, description, or custom properties. |
| Add account ledgers | `v0_AddAccountLedgers` | Add compatible ledgers to an existing account. |
| Lock account | `v0_LockAccount` | Prevent outbound activity for an account. |
| Unlock account | `v0_UnlockAccount` | Re-enable a locked account. |


## Create an account with the API

Create an account by submitting a `v0_CreateAccount` intent.

API reference:


```http
POST /v1/intents/dry-run
POST /v1/intents
```

The examples in this section show the intent `payload` block. When you dry run or propose the intent, include this payload inside the standard request body with the intent ID in `id` for dry runs or `request.id` for signed proposals. For the full request shapes, see [Intent request structure](/products/custody/governance/intents/intent-request-structure).

Before you create an account, prepare:

| Prerequisite | Additional information |
|  --- | --- |
| Vault ID | [List vaults](/products/custody/reference/api/openapi/vaults/getvaults) |
| Key strategy | Use the supported derivations returned by [Get vault details](/products/custody/reference/api/openapi/vaults/getvault). |
| Ledger IDs | Use [List ledgers](/products/custody/reference/api/openapi/ledgers/getledgers). |
| New IDs | Prepare an account ID and intent ID in standard UUID format. |



```json
{
  "payload": {
    "id": "3b6d578e-7396-495d-8392-61b7ede174b3",
    "alias": "btc-zero",
    "providerDetails": {
      "vaultId": "00000000-0000-0000-0000-000000000000",
      "keyStrategy": "VaultHard",
      "type": "Vault"
    },
    "ledgerIds": ["bitcoin-testnet"],
    "lock": "Unlocked",
    "description": "a bitcoin account for testing",
    "customProperties": {
      "testnet_account": "true"
    },
    "type": "v0_CreateAccount"
  }
}
```

Field notes:

| Field | Notes |
|  --- | --- |
| `providerDetails` | Vault and key strategy details. For more information, see [Key derivation](/products/custody/accounts-and-assets/accounts/account-key-derivation-and-ledger-compatibility). |
| `ledgerIds` | One or more ledger IDs associated with the account. |
| `lock` | Use `Locked` to create an inactive account and unlock it later. |
| `type` | `v0_CreateAccount`. |


Ledger-specific account limitations
Accounts you create on the Hedera ledger follow a specific account initialization process. For more information, see [Initialize Hedera accounts](/products/custody/accounts-and-assets/accounts/ledger-specific-settings/hedera-api).

Accounts you create on the Algorand ledger can only be used in offline mode on testnet and mainnet. They are in offline mode so cannot be used for consensus, although you can still use them to send and receive funds.

## View account details

Use account read operations to find account IDs, retrieve account details, and retrieve ledger addresses.

API reference:


```http
GET /v1/domains/{domainId}/accounts
GET /v1/domains/{domainId}/accounts/{accountId}
GET /v1/domains/{domainId}/accounts/{accountId}/addresses/{accountAddressId}
```

1. If you do not know the account ID, call [List accounts](/products/custody/reference/api/openapi/accounts/getaccounts). You can filter accounts by criteria such as ledger ID.
2. Call [Get account details](/products/custody/reference/api/openapi/accounts/getaccount) with the account ID.
3. To retrieve a specific account address, call [Retrieve account address](/products/custody/reference/api/openapi/accounts/getaccountaddress).


Depending on the account type, account details include:

| Account type | Details returned |
|  --- | --- |
| Single-ledger account | The ledger address in the `ledgerId` field. In `providerDetails`, `keyInformation` contains public key data and the derivation path for the ledger. |
| Multi-ledger account | The list of ledgers in `additionalDetails.ledgers`, including each ledger status. The `keys` array contains public key data and derivation paths for supported ledger curves. |


Multi-ledger account ledger statuses include:

| Status | Meaning |
|  --- | --- |
| `Activated` | The ledger is active for the account. |
| `Activating` | The ledger is currently being activated for the account. |
| `Available` | The ledger is available to be activated for the account. |
| `Unavailable` | The ledger is not compatible with the account's vault or key strategy. |


## Update account details

Use `v0_UpdateAccount` to update mutable account details such as alias, description, and custom properties.

API reference:


```http
POST /v1/intents/dry-run
POST /v1/intents
```

Submit an update intent with the current account reference:


```json
{
  "payload": {
    "reference": {
      "id": "3b6d578e-7396-495d-8392-61b7ede174b3",
      "revision": 2
    },
    "alias": "btc-zero",
    "description": "Updated account description",
    "customProperties": {},
    "type": "v0_UpdateAccount"
  }
}
```

## Add ledgers to an account

Use `v0_AddAccountLedgers` to add compatible ledgers to an existing account.

API reference:


```http
POST /v1/intents/dry-run
POST /v1/intents
```

Submit an add-ledgers intent with the current account reference:


```json
{
  "payload": {
    "reference": {
      "id": "3b6d578e-7396-495d-8392-61b7ede174b3",
      "revision": 2
    },
    "ledgerIds": ["ethereum-mainnet"],
    "type": "v0_AddAccountLedgers"
  }
}
```

## Lock or unlock an account

Use `v0_LockAccount` when an account should not be used for outbound activity. Use `v0_UnlockAccount` only after confirming the account should be re-enabled.

API reference:


```http
POST /v1/intents/dry-run
POST /v1/intents
```


```json
{
  "payload": {
    "reference": {
      "id": "3b6d578e-7396-495d-8392-61b7ede174b3",
      "revision": 2
    },
    "type": "v0_LockAccount"
  }
}
```

Use `v0_UnlockAccount` with the same reference shape to re-enable the account.

## Check account balances

Before you send assets, check the amount available to send. Balances depend on transaction state and ledger-specific behavior.

API reference:


```http
GET /v1/domains/{domainId}/accounts/{accountId}/balances
```

Account balances include:

| Amount | Description |
|  --- | --- |
| Total amount | Total balance reported by the blockchain. |
| Reserved amount | Balance allocated but not available for spending, including amounts and fees for transactions that are initiated but not yet executed. |
| Quarantined amount | Incoming transfers that are not yet released from quarantine. For more information, see [Release quarantined assets](/products/custody/transactions/send-and-receive/receive-assets-api#release-quarantined-assets). |
| Available amount | Balance available for new transactions. |


Call [Get account balances](/products/custody/reference/api/openapi/accounts/getaccountbalances).

## Force an account balance update

An account can receive funds directly from the blockchain that are not registered automatically in Ripple Custody. For example, staking rewards might not be reflected until balances are refreshed.

API reference:


```http
POST /v1/domains/{domainId}/accounts/{accountId}/balances/refresh
```

To force an account balance update, call [Update account balances forcefully](/products/custody/reference/api/openapi/accounts/forceupdateaccountbalances).

## Configure compliance settings

Use account-level compliance settings to control how incoming transfers are processed. The `skipQuarantineFrom` setting allows internal transfers to bypass quarantine screening. For more information, see [Skip quarantine for internal transfers](/products/custody/compliance/transaction-screening/concept#skip-quarantine-for-internal-transfers).

API reference:


```http
GET /v1/domains/{domainId}/accounts/{accountId}/compliance-configuration
PUT /v1/domains/{domainId}/accounts/{accountId}/compliance-configuration
GET /v1/domains/{domainId}/compliance-configurations
```

Before configuring compliance settings, prepare:

| Prerequisite | Additional information |
|  --- | --- |
| Account ID | [List accounts](/products/custody/reference/api/openapi/accounts/getaccounts) |
| Compliance role | Contact your domain administrator. |


To retrieve the current configuration for an account, call [Get compliance configuration](/products/custody/reference/api/openapi/accounts/getcomplianceconfiguration).

To create or update the configuration, call [Set compliance configuration](/products/custody/reference/api/openapi/accounts/upsertcomplianceconfiguration) with the desired `skipQuarantineFrom` value and revision:


```json
{
  "skipQuarantineFrom": "Domain",
  "revision": 1
}
```

| Value | Behavior |
|  --- | --- |
| `None` | All incoming transfers are quarantined normally. |
| `Domain` | Skip quarantine for transfers from accounts in the same domain. |
| `Instance` | Skip quarantine for transfers from any account in the same Ripple Custody instance. |


Always retrieve the current configuration before updating so you can use the correct revision number. To disable skip quarantine, set `skipQuarantineFrom` to `None`.

To retrieve all compliance configurations in a domain, call [List compliance configurations](/products/custody/reference/api/openapi/accounts/listcomplianceconfigurations).

## Operational checklist

Before submitting an account-management intent:

- Confirm the target domain.
- Confirm the vault ID, key strategy, and ledger IDs.
- Confirm the policy that will govern the account intent.
- Dry run the payload.
- Verify the executed change by viewing account details.