# Get deposit instructions

Returns the receiving details needed to deposit funds into an Axiym account belonging to the selected client.

**Before sending funds**

Send funds only from a whitelisted external bank account or wallet with status `ACTIVE` in the selected client's address book. Registration is followed by due diligence and compliance checks before activation.

**Instruction type**

Returns one instruction per transfer scheme the account accepts (`scheme`). Use the instruction for the scheme you send with.

- Bank instructions contain the beneficiary, the account number and the receiving bank for the scheme, an intermediary bank when the transfer passes through one, and, when present, an account-specific `reference`. Include the reference on the transfer.
- Wallet instructions (`BLOCKCHAIN`) contain the receiving beneficiary name, the wallet address, and the blockchain network to use.

Product: Client Account API
API reference version: 0.3.0 (current)
OpenAPI contract: https://docs.sandbox.axiym.io/openapi/client-account-api/0.3.0.yaml
Canonical page: https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/deposits/getDepositInstructions

[Compact reference](/client-account-api/api-reference/0.3.0/deposits/getDepositInstructions.md)

## GET /clients/{clientId}/accounts/{accountId}/deposit-instructions

## 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 Account API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### path: accountId

```json
{
  "name": "accountId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  },
  "description": "Account identifier (UUID)."
}
```

### 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"
    ]
  }
}
```

## Responses

### 200

```json
{
  "description": "Deposit instructions for the account, one per transfer scheme.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "nodes"
        ],
        "properties": {
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DepositInstruction"
            }
          }
        }
      },
      "examples": {
        "Bank transfer": {
          "summary": "Bank account with SWIFT and Fedwire",
          "value": {
            "nodes": [
              {
                "scheme": "SWIFT",
                "beneficiaryName": "Axi Labs AG",
                "beneficiaryAddress": {
                  "streetName": "Baarerstrasse",
                  "buildingNumber": "12",
                  "city": "Zug",
                  "postalCode": "6300",
                  "region": "Zug",
                  "country": "CH"
                },
                "accountNumber": "600000000",
                "swiftBic": "ZEITPRSJXXX",
                "bankName": "Zenus Bank International Inc",
                "bankAddress": {
                  "streetName": "Zenus Tower, 19th Floor, 252 Ponce de Leon",
                  "city": "San Juan",
                  "postalCode": "00918",
                  "country": "PR"
                },
                "intermediaryBank": {
                  "swiftBic": "CHASUS33XXX",
                  "clearingCode": "021000021",
                  "clearingSystemCode": "USABA",
                  "bankName": "JP Morgan Chase NA",
                  "bankAddress": {
                    "city": "New York",
                    "region": "NY",
                    "country": "US"
                  }
                },
                "reference": "RF11 0004 4901 01"
              },
              {
                "scheme": "FEDWIRE",
                "beneficiaryName": "Axi Labs AG",
                "beneficiaryAddress": {
                  "streetName": "Baarerstrasse",
                  "buildingNumber": "12",
                  "city": "Zug",
                  "postalCode": "6300",
                  "region": "Zug",
                  "country": "CH"
                },
                "accountNumber": "30000000000000",
                "clearingCode": "021000021",
                "clearingSystemCode": "USABA",
                "bankName": "JP Morgan Chase NA",
                "bankAddress": {
                  "city": "New York",
                  "region": "NY",
                  "country": "US"
                },
                "reference": "RF11 0004 4901 01"
              }
            ]
          }
        },
        "Book transfer": {
          "summary": "Book transfer",
          "value": {
            "nodes": [
              {
                "scheme": "BOOK",
                "beneficiaryName": "Axi Labs AG",
                "accountNumber": "A00123045"
              }
            ]
          }
        },
        "Wallet transfer": {
          "summary": "Wallet transfer",
          "value": {
            "nodes": [
              {
                "scheme": "BLOCKCHAIN",
                "beneficiaryName": "Axi Labs AG",
                "walletAddress": "TWd2yzw5yFc5W8Tq6CuNZcVJgfmLnBcT4Q",
                "network": "TRON"
              }
            ]
          }
        }
      }
    }
  }
}
```

### 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 '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": "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": [
    "Deposits"
  ],
  "operationId": "getDepositInstructions"
}
```

## Referenced definitions

- [`#/components/parameters/ClientId`](#definition-1)
- [`#/components/parameters/AccountId`](#definition-2)
- [`#/components/parameters/RequestId`](#definition-3)
- [`#/components/schemas/DepositInstruction`](#definition-4)
- [`#/components/schemas/BankDepositInstruction`](#definition-5)
- [`#/components/schemas/TransferScheme`](#definition-6)
- [`#/components/schemas/BankAddress`](#definition-7)
- [`#/components/schemas/CountryCode`](#definition-8)
- [`#/components/schemas/Iban`](#definition-9)
- [`#/components/schemas/DepositIntermediaryBank`](#definition-10)
- [`#/components/schemas/WalletDepositInstruction`](#definition-11)
- [`#/components/schemas/Network`](#definition-12)
- [`#/components/responses/BadRequest`](#definition-13)
- [`#/components/responses/Unauthorized`](#definition-14)
- [`#/components/responses/Forbidden`](#definition-15)
- [`#/components/responses/NotFound`](#definition-16)
- [`#/components/responses/InvalidParams`](#definition-17)
- [`#/components/schemas/ValidationFieldErrors`](#definition-18)
- [`#/components/schemas/ValidationError`](#definition-19)
- [`#/components/responses/InternalError`](#definition-20)

### 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 Account API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### definition-2

`#/components/parameters/AccountId`

```json
{
  "name": "accountId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  },
  "description": "Account identifier (UUID)."
}
```

### definition-3

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

`#/components/schemas/DepositInstruction`

```json
{
  "description": "Axiym's receiving details for one transfer scheme; the shape matches the scheme.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankDepositInstruction"
    },
    {
      "$ref": "#/components/schemas/WalletDepositInstruction"
    }
  ]
}
```

### definition-5

`#/components/schemas/BankDepositInstruction`

```json
{
  "type": "object",
  "title": "Bank transfer",
  "description": "Axiym's receiving bank details for one transfer scheme. Exactly one of `iban` and `accountNumber` is present. Bank fields are present when the scheme uses them.",
  "required": [
    "scheme",
    "beneficiaryName"
  ],
  "properties": {
    "scheme": {
      "$ref": "#/components/schemas/TransferScheme"
    },
    "beneficiaryName": {
      "type": "string",
      "description": "Name of the receiving party to put on the transfer.",
      "examples": [
        "Axi Labs AG"
      ]
    },
    "beneficiaryAddress": {
      "allOf": [
        {
          "$ref": "#/components/schemas/BankAddress"
        }
      ],
      "description": "Postal address of the receiving party. `country` is always present."
    },
    "iban": {
      "$ref": "#/components/schemas/Iban",
      "description": "IBAN to send to. Present instead of `accountNumber` when the account is identified by an IBAN."
    },
    "accountNumber": {
      "type": "string",
      "description": "Account number to send to. Present instead of `iban` when the account has no IBAN.",
      "examples": [
        "600000000"
      ]
    },
    "swiftBic": {
      "type": "string",
      "description": "SWIFT/BIC code of the receiving bank.",
      "examples": [
        "ZEITPRSJXXX"
      ]
    },
    "clearingCode": {
      "type": "string",
      "description": "Local clearing or routing code of the receiving bank (for example the ABA routing number for Fedwire and ACH).",
      "examples": [
        "021000021"
      ]
    },
    "clearingSystemCode": {
      "type": "string",
      "description": "Clearing system `clearingCode` belongs to. Present together with `clearingCode`.",
      "examples": [
        "USABA"
      ]
    },
    "bankName": {
      "type": "string",
      "description": "Receiving bank name.",
      "examples": [
        "Zenus Bank International Inc"
      ]
    },
    "bankAddress": {
      "allOf": [
        {
          "$ref": "#/components/schemas/BankAddress"
        }
      ],
      "description": "Postal address of the receiving bank. `country` is always present."
    },
    "intermediaryBank": {
      "$ref": "#/components/schemas/DepositIntermediaryBank"
    },
    "reference": {
      "type": "string",
      "description": "ISO 11649 creditor reference (`RF` + check digits) assigned by Axiym, formatted in groups of four. Present when the account is funded through a shared receiving account; include it on the transfer so the deposit is matched automatically (matching ignores the spaces). Absent when the receiving account number alone identifies the Axiym account.",
      "examples": [
        "RF11 0004 4901 01"
      ]
    }
  }
}
```

### definition-6

`#/components/schemas/TransferScheme`

```json
{
  "type": "string",
  "description": "Transfer scheme the instruction applies to. `BOOK` is a transfer between accounts held at the same provider; `BLOCKCHAIN` is a wallet transfer.",
  "enum": [
    "SWIFT",
    "FEDWIRE",
    "ACH",
    "SEPA",
    "FPS",
    "BOOK",
    "BLOCKCHAIN"
  ]
}
```

### definition-7

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

`#/components/schemas/CountryCode`

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

### definition-9

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

`#/components/schemas/DepositIntermediaryBank`

```json
{
  "type": "object",
  "description": "Bank the transfer passes through before the receiving bank. Present when the scheme uses one; put it on the transfer as the intermediary bank.",
  "properties": {
    "swiftBic": {
      "type": "string",
      "description": "SWIFT/BIC code of the intermediary bank.",
      "examples": [
        "CHASUS33XXX"
      ]
    },
    "clearingCode": {
      "type": "string",
      "description": "Local clearing or routing code of the intermediary bank.",
      "examples": [
        "021000021"
      ]
    },
    "clearingSystemCode": {
      "type": "string",
      "description": "Clearing system `clearingCode` belongs to. Present together with `clearingCode`.",
      "examples": [
        "USABA"
      ]
    },
    "bankName": {
      "type": "string",
      "description": "Intermediary bank name.",
      "examples": [
        "JP Morgan Chase NA"
      ]
    },
    "bankAddress": {
      "allOf": [
        {
          "$ref": "#/components/schemas/BankAddress"
        }
      ],
      "description": "Postal address of the intermediary bank. `country` is always present."
    }
  }
}
```

### definition-11

`#/components/schemas/WalletDepositInstruction`

```json
{
  "type": "object",
  "title": "Wallet transfer",
  "required": [
    "scheme",
    "beneficiaryName",
    "walletAddress",
    "network"
  ],
  "properties": {
    "scheme": {
      "type": "string",
      "enum": [
        "BLOCKCHAIN"
      ],
      "description": "Always `BLOCKCHAIN` for a wallet instruction."
    },
    "beneficiaryName": {
      "type": "string",
      "description": "Name of the receiving party the address belongs to. The transfer itself carries no name; use it in your own records.",
      "examples": [
        "Axi Labs AG"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Deposit address of the account; deposits are matched by the address itself.",
      "examples": [
        "TWd2yzw5yFc5W8Tq6CuNZcVJgfmLnBcT4Q"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    }
  }
}
```

### definition-12

`#/components/schemas/Network`

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

### definition-13

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

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

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

`#/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 '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-17

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

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

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

`#/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"
        ]
      }
    }
  }
}
```