# List address book entries

Returns the external bank accounts and wallets registered in your address book, including their current status. Filter the results by currency or status.

An external account is whitelisted for deposits and withdrawals when its status is `ACTIVE`.

Product: Account API
API reference version: 0.1.0 (current)
OpenAPI contract: https://docs.sandbox.axiym.io/openapi/account-api/0.1.0.yaml
Canonical page: https://docs.sandbox.axiym.io/account-api/api-reference/0.1.0/address-book/listAddressBookEntries

[Compact reference](/account-api/api-reference/0.1.0/address-book/listAddressBookEntries.md)

## GET /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

### 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 your 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": "The request is malformed or cannot be processed as supplied.",
  "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": "Authentication is missing or invalid.",
  "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": "Your access token does not permit this operation or access to the requested resource.",
  "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": "The requested resource was not found.",
  "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 'Account 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
          }
        },
        "Account not found": {
          "summary": "Account not found",
          "value": {
            "code": 404,
            "message": "Account 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": "An unexpected server error prevented the request from completing.",
  "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/RequestId`](#definition-1)
- [`#/components/parameters/First`](#definition-2)
- [`#/components/parameters/After`](#definition-3)
- [`#/components/schemas/Currency`](#definition-4)
- [`#/components/schemas/DestinationStatus`](#definition-5)
- [`#/components/schemas/AddressBookEntry`](#definition-6)
- [`#/components/schemas/BankAddressBookEntry`](#definition-7)
- [`#/components/schemas/Iban`](#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/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-2

`#/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-3

`#/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-4

`#/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-5

`#/components/schemas/DestinationStatus`

```json
{
  "type": "string",
  "description": "`PENDING_REVIEW` awaits due diligence and compliance checks. `ACTIVE` is whitelisted for deposits and withdrawals. `SUSPENDED` is temporarily unavailable. `CLOSED` is permanently retired.",
  "enum": [
    "PENDING_REVIEW",
    "ACTIVE",
    "SUSPENDED",
    "CLOSED"
  ],
  "examples": [
    "ACTIVE"
  ]
}
```

### definition-6

`#/components/schemas/AddressBookEntry`

```json
{
  "description": "A registered external bank account or wallet in your address book. Its status indicates whether it is whitelisted for deposits and withdrawals.\n\nA bank account contains either `iban` or `accountNumber`, together with `bank`. A wallet contains `walletAddress` and `network`. The two field sets never appear together.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankAddressBookEntry"
    },
    {
      "$ref": "#/components/schemas/WalletAddressBookEntry"
    }
  ]
}
```

### definition-7

`#/components/schemas/BankAddressBookEntry`

```json
{
  "type": "object",
  "title": "Bank account",
  "description": "A registered external bank account. Exactly one of `iban` and `accountNumber` is present.",
  "required": [
    "destinationId",
    "status",
    "currency",
    "bank"
  ],
  "oneOf": [
    {
      "title": "IBAN",
      "required": [
        "iban"
      ]
    },
    {
      "title": "Account number",
      "required": [
        "accountNumber"
      ]
    }
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the external account in your address book (UUID).",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Review and availability status of the registered external account.",
      "examples": [
        "ACTIVE"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the registered external account.",
      "examples": [
        "USD"
      ]
    },
    "iban": {
      "$ref": "#/components/schemas/Iban",
      "description": "IBAN of the account. Present instead of `accountNumber` when the account is identified by an IBAN."
    },
    "accountNumber": {
      "type": "string",
      "description": "Domestic bank account number. Present instead of `iban` when the account has no IBAN.",
      "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-8

`#/components/schemas/Iban`

```json
{
  "type": "string",
  "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{10,30}$",
  "description": "International Bank Account Number in electronic format — no spaces, upper case. Its check digits are verified; country-specific lengths are left to the receiving bank.",
  "examples": [
    "LU364080000000711363"
  ]
}
```

### 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": "Identifier of the external account in your address book (UUID).",
      "examples": [
        "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Review and availability status of the registered external account.",
      "examples": [
        "ACTIVE"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the registered external account.",
      "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": "The request is malformed or cannot be processed as supplied.",
  "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": "Authentication is missing or invalid.",
  "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": "Your access token does not permit this operation or access to the requested resource.",
  "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": "The requested resource was not found.",
  "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 'Account 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
          }
        },
        "Account not found": {
          "summary": "Account not found",
          "value": {
            "code": 404,
            "message": "Account 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": "Identifier of the validation rule that failed, such as `length` or `invalid_currency`.",
      "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": "An unexpected server error prevented the request from completing.",
  "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"
        ]
      }
    }
  }
}
```