---
updatedAt: 2026-08-13T02:50:41.000Z
agentTools:
  projectIndex: https://docs.zerohash.com/llms.txt
---

# Managing linked accounts API Workflow

Manage external accounts through the zerohash API.

Whether created via SDK with [zerohash Powered Plaid Link](https://docs.zerohash.com/docs/zerohash-powered-plaid-link), or created directly through the zerohash API with [Self Service Plaid Link](https://docs.zerohash.com/docs/self-service-plaid-link), external accounts can always be managed by platforms through the zerohash API.

## Create external account

[POST /payments/external\_accounts](https://docs.zerohash.com/zerohash/reference/post_payments-external-accounts)

*This API call is only relevant to platforms using [Self Service Plaid Link](https://docs.zerohash.com/docs/self-service-plaid-link). Platforms using [zerohash Powered Plaid Link](https://docs.zerohash.com/docs/zerohash-powered-plaid-link) should [invoke the zerohash SDK](https://docs.zerohash.com/reference/sdk-modules-fiat-account-link) to link a new bank account.*

### Sample request

```json
{
    "message": {
        "participant_code": "ABC123",
        "account_nickname": "Chase",
        "plaid_processor_token": "db884a3e-7eb7-4253-92ee-04ff5efbc365"
    }
}
```

### Sample response

```json
{
    "message": {
        "request_id": "0f65678e-2114-469d-b505-c850d776e078",
        "participant_code": "ABC123",
        "platform_code": "XYZ789",
        "account_nickname": "Chase",
        "account_type": "checking",
        "external_account_id": "0f68333e-2114-469d-b505-c850d776e063",
        "created_at": 1561996924964
    }
}
```

## Close external accounts

[POST /payments/external\_accounts/{external_account_id}/close](https://docs.zerohash.com/reference/post_payments-external-accounts-external-account-id-close)

This enables closing a customer bank account so it cannot be used with zerohash any longer.

### Sample response

```json
{
    "message": {
        "request_id": "0f65678e-2114-469d-b505-c850d776e078",
        "participant_code": "ABC123",
        "platform_code": "XYZ789",
        "account_nickname": "Chase",
        "account_type": "checking",
        "external_account_id": "0f68333e-2114-469d-b505-c850d776e063",
        "status": "closed",
        "created_at": 1561996924964
    }
}
```

##

## Get external accounts

External account updates can be [fetched via API](https://docs.zerohash.com/zerohash/reference/get_payments-external-accounts), and [received via external account status webhooks](https://docs.zerohash.com/reference/external-account-status-updates).

### Query parameters include

* `page`: (optional) the page you would like to request – default value is 1
* `size`: (optional) the number of records per page – default value is 200
* `participants`: (optional) array of the participants for which to filter the result

Returns an array of all accounts that have been posted for ACH transactions.

### Response parameters

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Description",
    "h-2": "Type",
    "0-0": "request_id",
    "0-1": "The unique identifier generated by zerohash associated with the request.",
    "0-2": "string",
    "1-0": "account_number",
    "1-1": "The full bank account number of the external account. Value will be empty because of the Plaid token relationship.",
    "1-2": "string",
    "2-0": "routing_number",
    "2-1": "The routing number of the bank where the external account is held. Value will be empty because of the Plaid token relationship.",
    "2-2": "string",
    "3-0": "participant_code",
    "3-1": "The code of the participant that wants to create a new ACH transaction, required.",
    "3-2": "string",
    "4-0": "platform_code",
    "4-1": "Platform unique identifier.",
    "4-2": "string",
    "5-0": "account_nickname",
    "5-1": "Name given to the account. This does not impact further zerohash functionality so it is purely for platform reference.",
    "5-2": "string",
    "6-0": "account_type",
    "6-1": "Indicates if the account is checking or savings.",
    "6-2": "string",
    "7-0": "status",
    "7-1": "Account status. Could be one of the following:  \n`pending` `approved` `rejected` `locked` `disabled` `rejected` `closed`",
    "7-2": "string",
    "8-0": "external_account_id",
    "8-1": "The unique identifier generated by zerohash for the account. This must be stored and used to make subsequent payment requests.",
    "8-2": "string",
    "9-0": "created_at",
    "9-1": "Timestamp when the account was created.",
    "9-2": "timestamp",
    "10-0": "updated_at",
    "10-1": "Timestamp when the account was last changed.",
    "10-2": "timestamp"
  },
  "cols": 3,
  "rows": 11,
  "align": [
    null,
    null,
    null
  ]
}
[/block]

### Sample response

```json
{
    "message": [
        {
            "request_id": "0f68333e-2114-469d-b505-c850d776e063",
            "account_number": "",
            "routing_number": "",
            "participant_code": "ALI123",
            "platform_code": "TES123",
            "account_nickname": "test1",
            "account_type": "checking",
            "external_account_id": "0f68333e-2114-469d-b505-c850d776e063",
            "created_at": "1975-08-19T23:15:30.000Z",
            "updated_at": "1975-08-19T23:15:30.000Z"
        }
    ],
    "page": 1,
    "total_pages": 1,
    "page_size": 200,
    "count": 10
}
```