# List address book entries

Returns the entries in the client's address book: the external bank accounts and wallets registered for the client. Filter the results by currency or status.
An `ACTIVE` account may fund the client's deposits and receive the client's withdrawals.

Product: Client Trade API
API reference version: 0.3.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/trade-api/0.3.0.yaml
Canonical page: https://docs.axiym.io/trade-api/api-reference/0.3.0/address-book/listAddressBookEntries

[Compact reference](/trade-api/api-reference/0.3.0/address-book/listAddressBookEntries.md)

## GET /clients/{clientId}/address-book

## Servers

```json
[
  {
    "url": "https://partner-api.sandbox.axiym.io/api/v1",
    "description": "Sandbox"
  },
  {
    "url": "https://partner-api.axiym.io/api/v1",
    "description": "Production"
  }
]
```

## Authentication

```json
{
  "security": [
    {
      "Default": []
    }
  ],
  "securitySchemes": {
    "Default": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}
```

## Parameters

### path: clientId

```json
{
  "name": "clientId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f"
    ]
  },
  "description": "Client identifier (UUID) assigned when an onboarding case is created. It identifies the onboarding case and, once active, the client's Client Trade API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### header: X-Request-Id

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### query: first

```json
{
  "name": "first",
  "in": "query",
  "description": "Maximum number of items to return (page size).",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 20,
    "examples": [
      20
    ]
  }
}
```

### query: after

```json
{
  "name": "after",
  "in": "query",
  "description": "Cursor for the next page, from the previous response's pageInfo.endCursor.",
  "schema": {
    "type": "string",
    "examples": [
      "eyJvZmZzZXQiOjI1fQ=="
    ]
  }
}
```

### query: currency

```json
{
  "name": "currency",
  "in": "query",
  "schema": {
    "$ref": "#/components/schemas/Currency",
    "examples": [
      "USD"
    ]
  },
  "description": "Filter by currency."
}
```

### query: status

```json
{
  "name": "status",
  "in": "query",
  "schema": {
    "$ref": "#/components/schemas/DestinationStatus",
    "examples": [
      "ACTIVE"
    ]
  },
  "description": "Filter by status."
}
```

## Responses

### 200

```json
{
  "description": "Page of the client's address book entries.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "nodes",
          "pageInfo"
        ],
        "properties": {
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AddressBookEntry"
            }
          },
          "pageInfo": {
            "$ref": "#/components/schemas/PageInfo"
          }
        }
      },
      "examples": {
        "Address book entries": {
          "summary": "A bank account and a wallet address",
          "value": {
            "nodes": [
              {
                "destinationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "status": "ACTIVE",
                "currency": "USD",
                "accountNumber": "0123456789",
                "bank": {
                  "bankName": "Bank of America",
                  "address": {
                    "city": "New York",
                    "country": "US"
                  },
                  "swiftBic": "BOFAUS3NXXX"
                },
                "createdAt": "2026-06-12T14:05:00Z"
              },
              {
                "destinationId": "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c",
                "status": "ACTIVE",
                "currency": "USDT",
                "walletAddress": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL",
                "network": "TRON",
                "createdAt": "2026-06-12T14:05:00Z"
              }
            ],
            "pageInfo": {
              "hasNextPage": false
            }
          }
        }
      }
    }
  }
}
```

### 400

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 401

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 403

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 404

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Client Not Found'."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        },
        "Client not found": {
          "summary": "Client not found",
          "value": {
            "code": 404,
            "message": "Client Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 422

```json
{
  "description": "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Flat field errors": {
          "summary": "Flat field errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalEntityName": [
                {
                  "code": "length",
                  "message": null,
                  "params": {
                    "value": "",
                    "min": 1
                  }
                }
              ],
              "currency": [
                {
                  "code": "invalid_currency",
                  "message": null,
                  "params": {
                    "value": "ZZZ"
                  }
                }
              ]
            }
          }
        },
        "Nested struct errors": {
          "summary": "Nested struct errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalAddress": {
                "country": [
                  {
                    "code": "invalid_country",
                    "message": null,
                    "params": {
                      "value": "INVALID"
                    }
                  }
                ],
                "postalCode": [
                  {
                    "code": "length",
                    "message": null,
                    "params": {
                      "value": "",
                      "min": 1
                    }
                  }
                ]
              }
            }
          }
        },
        "List item errors": {
          "summary": "List item errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "authorizedDirectors": {
                "0": {
                  "firstName": [
                    {
                      "code": "length",
                      "message": null,
                      "params": {
                        "value": "",
                        "min": 1
                      }
                    }
                  ],
                  "email": [
                    {
                      "code": "email",
                      "message": null,
                      "params": {
                        "value": "not-an-email"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "Custom validator": {
          "summary": "Custom validator",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "disbursementAccount": [
                {
                  "code": "disbursement_account_required",
                  "message": null,
                  "params": {
                    "value": null
                  }
                }
              ]
            }
          }
        },
        "Business rejection": {
          "summary": "Business rejection",
          "value": {
            "code": 422,
            "message": "Documents Not Accepted",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 500

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

## Operation metadata

```json
{
  "tags": [
    "Address Book"
  ],
  "operationId": "listAddressBookEntries"
}
```

## Referenced definitions

- [`#/components/parameters/ClientId`](#definition-1)
- [`#/components/parameters/RequestId`](#definition-2)
- [`#/components/parameters/First`](#definition-3)
- [`#/components/parameters/After`](#definition-4)
- [`#/components/schemas/Currency`](#definition-5)
- [`#/components/schemas/DestinationStatus`](#definition-6)
- [`#/components/schemas/AddressBookEntry`](#definition-7)
- [`#/components/schemas/BankAddressBookEntry`](#definition-8)
- [`#/components/schemas/Bank`](#definition-9)
- [`#/components/schemas/BankAddress`](#definition-10)
- [`#/components/schemas/CountryCode`](#definition-11)
- [`#/components/schemas/WalletAddressBookEntry`](#definition-12)
- [`#/components/schemas/Network`](#definition-13)
- [`#/components/schemas/PageInfo`](#definition-14)
- [`#/components/responses/BadRequest`](#definition-15)
- [`#/components/responses/Unauthorized`](#definition-16)
- [`#/components/responses/Forbidden`](#definition-17)
- [`#/components/responses/NotFound`](#definition-18)
- [`#/components/responses/InvalidParams`](#definition-19)
- [`#/components/schemas/ValidationFieldErrors`](#definition-20)
- [`#/components/schemas/ValidationError`](#definition-21)
- [`#/components/responses/InternalError`](#definition-22)

### definition-1

`#/components/parameters/ClientId`

```json
{
  "name": "clientId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f"
    ]
  },
  "description": "Client identifier (UUID) assigned when an onboarding case is created. It identifies the onboarding case and, once active, the client's Client Trade API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### definition-2

`#/components/parameters/RequestId`

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### definition-3

`#/components/parameters/First`

```json
{
  "name": "first",
  "in": "query",
  "description": "Maximum number of items to return (page size).",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 20,
    "examples": [
      20
    ]
  }
}
```

### definition-4

`#/components/parameters/After`

```json
{
  "name": "after",
  "in": "query",
  "description": "Cursor for the next page, from the previous response's pageInfo.endCursor.",
  "schema": {
    "type": "string",
    "examples": [
      "eyJvZmZzZXQiOjI1fQ=="
    ]
  }
}
```

### definition-5

`#/components/schemas/Currency`

```json
{
  "type": "string",
  "description": "Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).",
  "examples": [
    "USD"
  ]
}
```

### definition-6

`#/components/schemas/DestinationStatus`

```json
{
  "type": "string",
  "description": "`PENDING_REVIEW` awaits review. `ACTIVE` may fund deposits and receive withdrawals. `SUSPENDED` is temporarily unavailable. `CLOSED` is permanently retired.\n",
  "enum": [
    "PENDING_REVIEW",
    "ACTIVE",
    "SUSPENDED",
    "CLOSED"
  ],
  "examples": [
    "ACTIVE"
  ]
}
```

### definition-7

`#/components/schemas/AddressBookEntry`

```json
{
  "description": "An address book entry — a registered external bank account or wallet owned by the client. The variant is signaled by its fields: a bank destination carries `accountNumber` and the `bank` block; a wallet destination carries `walletAddress` and `network`. The two sets never appear together.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankAddressBookEntry"
    },
    {
      "$ref": "#/components/schemas/WalletAddressBookEntry"
    }
  ]
}
```

### definition-8

`#/components/schemas/BankAddressBookEntry`

```json
{
  "type": "object",
  "title": "Bank account",
  "required": [
    "destinationId",
    "status",
    "currency",
    "accountNumber",
    "bank"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry identifier (UUID).",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Address book entry status.",
      "examples": [
        "ACTIVE"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the address book entry.",
      "examples": [
        "USD"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Bank account number.",
      "examples": [
        "0123456789"
      ]
    },
    "bank": {
      "$ref": "#/components/schemas/Bank",
      "description": "Destination bank details."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-06-12T14:05:00Z"
      ]
    }
  }
}
```

### definition-9

`#/components/schemas/Bank`

```json
{
  "type": "object",
  "description": "Destination bank details. Present on bank destinations only. The address country selects the applicable corridor rules.",
  "additionalProperties": false,
  "required": [
    "bankName",
    "address"
  ],
  "properties": {
    "bankName": {
      "type": "string",
      "minLength": 1,
      "description": "Bank name.",
      "examples": [
        "Bank of America"
      ]
    },
    "address": {
      "$ref": "#/components/schemas/BankAddress"
    },
    "swiftBic": {
      "type": "string",
      "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
      "description": "ISO 9362 SWIFT/BIC, when required for the corridor.",
      "examples": [
        "BOFAUS3NXXX"
      ]
    },
    "clearingCode": {
      "type": "string",
      "description": "Local clearing or routing code, when required for the corridor.",
      "examples": [
        "026009593"
      ]
    },
    "clearingSystemCode": {
      "type": "string",
      "description": "Clearing system the code belongs to. Axiym derives it from the bank country; supply it where a country has more than one system.",
      "examples": [
        "USABA"
      ]
    }
  }
}
```

### definition-10

`#/components/schemas/BankAddress`

```json
{
  "type": "object",
  "description": "Postal address of the bank. Only the country is required — it selects the corridor rules. Supply the rest when the corridor or a correspondent asks for it.",
  "additionalProperties": false,
  "required": [
    "country"
  ],
  "properties": {
    "streetName": {
      "type": "string"
    },
    "buildingNumber": {
      "type": "string"
    },
    "city": {
      "type": "string",
      "examples": [
        "New York"
      ]
    },
    "region": {
      "type": "string"
    },
    "postalCode": {
      "type": "string"
    },
    "country": {
      "$ref": "#/components/schemas/CountryCode"
    }
  }
}
```

### definition-11

`#/components/schemas/CountryCode`

```json
{
  "type": "string",
  "pattern": "^[A-Z]{2}$",
  "description": "ISO 3166-1 alpha-2 country code.",
  "examples": [
    "US"
  ]
}
```

### definition-12

`#/components/schemas/WalletAddressBookEntry`

```json
{
  "type": "object",
  "title": "Wallet address",
  "required": [
    "destinationId",
    "status",
    "currency",
    "walletAddress",
    "network"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry identifier (UUID).",
      "examples": [
        "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Address book entry status.",
      "examples": [
        "ACTIVE"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the address book entry.",
      "examples": [
        "USDT"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Wallet address of the entry; static and reusable.",
      "examples": [
        "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-06-12T14:05:00Z"
      ]
    }
  }
}
```

### definition-13

`#/components/schemas/Network`

```json
{
  "type": "string",
  "description": "Wallet network.",
  "enum": [
    "TRON",
    "AVALANCHE"
  ],
  "examples": [
    "TRON"
  ]
}
```

### definition-14

`#/components/schemas/PageInfo`

```json
{
  "type": "object",
  "properties": {
    "hasNextPage": {
      "type": "boolean",
      "description": "When paginating forwards, are there more items?",
      "examples": [
        true
      ]
    },
    "endCursor": {
      "type": "string",
      "description": "When paginating forwards, the cursor to continue.",
      "examples": [
        "eyJvZmZzZXQiOjI1fQ=="
      ]
    }
  },
  "required": [
    "hasNextPage"
  ]
}
```

### definition-15

`#/components/responses/BadRequest`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-16

`#/components/responses/Unauthorized`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-17

`#/components/responses/Forbidden`

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-18

`#/components/responses/NotFound`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Client Not Found'."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        },
        "Client not found": {
          "summary": "Client not found",
          "value": {
            "code": 404,
            "message": "Client Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-19

`#/components/responses/InvalidParams`

```json
{
  "description": "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Flat field errors": {
          "summary": "Flat field errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalEntityName": [
                {
                  "code": "length",
                  "message": null,
                  "params": {
                    "value": "",
                    "min": 1
                  }
                }
              ],
              "currency": [
                {
                  "code": "invalid_currency",
                  "message": null,
                  "params": {
                    "value": "ZZZ"
                  }
                }
              ]
            }
          }
        },
        "Nested struct errors": {
          "summary": "Nested struct errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalAddress": {
                "country": [
                  {
                    "code": "invalid_country",
                    "message": null,
                    "params": {
                      "value": "INVALID"
                    }
                  }
                ],
                "postalCode": [
                  {
                    "code": "length",
                    "message": null,
                    "params": {
                      "value": "",
                      "min": 1
                    }
                  }
                ]
              }
            }
          }
        },
        "List item errors": {
          "summary": "List item errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "authorizedDirectors": {
                "0": {
                  "firstName": [
                    {
                      "code": "length",
                      "message": null,
                      "params": {
                        "value": "",
                        "min": 1
                      }
                    }
                  ],
                  "email": [
                    {
                      "code": "email",
                      "message": null,
                      "params": {
                        "value": "not-an-email"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "Custom validator": {
          "summary": "Custom validator",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "disbursementAccount": [
                {
                  "code": "disbursement_account_required",
                  "message": null,
                  "params": {
                    "value": null
                  }
                }
              ]
            }
          }
        },
        "Business rejection": {
          "summary": "Business rejection",
          "value": {
            "code": 422,
            "message": "Documents Not Accepted",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-20

`#/components/schemas/ValidationFieldErrors`

```json
{
  "description": "Nested validation errors keyed by field name or array index. Leaf values are arrays of `ValidationError` objects.",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      }
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/ValidationFieldErrors"
      },
      "properties": {}
    }
  ]
}
```

### definition-21

`#/components/schemas/ValidationError`

```json
{
  "type": "object",
  "description": "One field-level validation error.",
  "properties": {
    "code": {
      "type": "string",
      "description": "Validation rule code (e.g. 'length', 'email', 'invalid_currency', 'disbursement_account_required').",
      "examples": [
        "length"
      ]
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable message.",
      "examples": [
        "string"
      ]
    },
    "params": {
      "type": "object",
      "description": "Rule-specific parameters. Always includes `value` (the offending input). Additional keys depend on the rule (e.g. `min`, `max` for length).",
      "properties": {
        "value": {
          "description": "The submitted value that failed validation.",
          "examples": [
            "string"
          ]
        }
      }
    }
  },
  "required": [
    "code",
    "params"
  ]
}
```

### definition-22

`#/components/responses/InternalError`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```