> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a recipient > Creates an address book recipient. Required fields depend on your Circle entity; use the request body options that match your integration. Validation failures can return error codes in the `2024`–`2037` range (for example `2024` when `identity` is required but missing, `2025` when `ownership` is required but missing). ## OpenAPI ````yaml openapi/payouts.yaml post /v1/addressBook/recipients openapi: 3.0.2 info: version: ${version} title: Crypto Payouts API description: >- The Circle Payouts API allows you to programmatically make fast, global payouts to your customers, vendors, and suppliers. Make payouts on supported blockchains. servers: - url: https://api-sandbox.circle.com - url: https://api.circle.com security: [] tags: - name: Payouts description: Create and get information on address book payouts. - name: Crypto Address Book description: Manage blockchain addresses with metadata. paths: /v1/addressBook/recipients: post: tags: - Crypto Address Book summary: Create a recipient description: > Creates an address book recipient. Required fields depend on your Circle entity; use the request body options that match your integration. Validation failures can return error codes in the `2024`–`2037` range (for example `2024` when `identity` is required but missing, `2025` when `ownership` is required but missing). operationId: createAddressBookRecipient requestBody: content: application/json: schema: oneOf: - title: General customers description: For Circle entities other than CIRCLE_SG. allOf: - $ref: '#/components/schemas/AddressBookRecipientRequestGeneral' - title: SG customers description: For Singapore (CIRCLE_SG) entities. allOf: - $ref: '#/components/schemas/AddressBookRecipientRequestBase' - type: object required: - identity - ownership properties: identity: allOf: - $ref: >- #/components/schemas/AddressBookRecipientIdentity - required: - type ownership: $ref: '#/components/schemas/AddressBookRecipientOwnership' responses: '201': description: Successfully created an address book recipient. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: title: CreateAddressBookRecipientResponse properties: data: $ref: '#/components/schemas/AddressBookRecipientResponseData' examples: generalCustomers: summary: General customers description: For Circle entities other than CIRCLE_SG. value: data: id: 8755d0ea-14f9-4259-b092-de23c14b6568 chain: ETH address: '0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3' metadata: nickname: sample nickname email: satoshi@circle.com bns: sample.circle status: pending identity: type: individual firstName: Ada lastName: Lovelace createDate: '2022-07-21T20:13:35.578678Z' updateDate: '2022-07-21T20:19:24.859052Z' sgCustomers: summary: SG customers description: For Singapore (CIRCLE_SG) entities. value: data: id: 8755d0ea-14f9-4259-b092-de23c14b6568 chain: ETH address: '0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3' metadata: nickname: sample nickname email: satoshi@circle.com bns: sample.circle status: pending identity: type: individual firstName: Ada lastName: Lovelace ownership: type: third_party custody: type: hosted vaspId: 550e8400-e29b-41d4-a716-446655440000 createDate: '2022-07-21T20:13:35.578678Z' updateDate: '2022-07-21T20:19:24.859052Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' security: - bearerAuth: [] components: schemas: AddressBookRecipientRequestGeneral: allOf: - $ref: '#/components/schemas/AddressBookRecipientRequestBase' - type: object properties: identity: $ref: '#/components/schemas/AddressBookRecipientIdentity' AddressBookRecipientRequestBase: type: object required: - idempotencyKey - chain - address - metadata properties: idempotencyKey: $ref: '#/components/schemas/IdempotencyKey' chain: $ref: '#/components/schemas/AddressBookRecipientChain' address: $ref: '#/components/schemas/Address' addressTag: $ref: '#/components/schemas/AddressTag' metadata: $ref: '#/components/schemas/AddressBookRecipientMetadata' AddressBookRecipientIdentity: type: object description: > Beneficiary identity for the address book entry. When `type` is `individual`, include `firstName` and `lastName`. When `type` is `business`, include `businessName`. Related validation error codes include `2024` (identity missing), `2031`–`2034`, and `2036` (identity cannot be updated via PATCH). properties: type: type: string description: Whether the beneficiary is an individual or a business. enum: - individual - business firstName: type: string description: Required when `type` is `individual`. example: Ada lastName: type: string description: Required when `type` is `individual`. example: Lovelace businessName: type: string description: Legal business name. Required when `type` is `business`. example: Example Corp AddressBookRecipientOwnership: type: object description: > Ownership and custody of the wallet for Travel Rule and compliance. Validation errors can include codes such as `2025` (ownership missing), `2026` (VASP ID missing when required), `2027`–`2030`, `2035` (VASP ID not allowed when custody is `self_hosted`), and `2037` (ownership cannot be updated via PATCH). required: - type - custody properties: type: type: string description: Whether the wallet is first-party or third-party. enum: - first_party - third_party custody: $ref: '#/components/schemas/AddressBookRecipientCustody' AddressBookRecipientResponseData: oneOf: - title: General customers description: For Circle entities other than CIRCLE_SG. allOf: - $ref: '#/components/schemas/AddressBookRecipientResponseGeneral' - type: object properties: identity: $ref: '#/components/schemas/AddressBookRecipientIdentityResponse' createDate: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' - title: SG customers description: For Singapore (CIRCLE_SG) entities. allOf: - $ref: '#/components/schemas/AddressBookRecipientResponseGeneral' - type: object properties: identity: $ref: '#/components/schemas/AddressBookRecipientIdentityResponse' ownership: $ref: '#/components/schemas/AddressBookRecipientOwnershipResponse' createDate: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' IdempotencyKey: type: string description: >- Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. format: uuid example: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 AddressBookRecipientChain: type: string description: Blockchain network code for the recipient address (address book scope). enum: - ALGO - APTOS - ARB - AVAX - BASE - CELO - ETH - HBAR - NEAR - NOBLE - OP - PAH - POLY - SOL - SUI - UNI - XLM - XRP - ZKS Address: type: string description: > An alphanumeric string representing a blockchain address. Formatting varies by blockchain. Be sure to preserve the exact formatting and capitalization of the address. **Important:** For Ripple (XRP) addresses, only the classic address format is supported (for example, `rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY`). The `x-address` format is NOT supported currently (for example, `XV5sbjUmgPpvXv4ixFWZ5ptAYZ6PD2q1qM6owqNbug8W6KV`). example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' AddressTag: type: string description: >- The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, id, or hash format. nullable: true example: '123456789' AddressBookRecipientMetadata: type: object properties: nickname: type: string description: Nickname related to the address. example: sample nickname email: $ref: '#/components/schemas/Email' bns: type: string description: Blockchain Name Service (e.g. ENS) domain for the address. example: sample.circle lei: $ref: '#/components/schemas/LegalEntityIdentifier' AddressBookRecipientCustody: type: object description: > Wallet custody details. When `type` is `hosted`, `vaspId` is required and must match an identifier returned by `GET /v1/addressBook/vasps`. When `type` is `self_hosted`, do not send `vaspId`. required: - type properties: type: type: string description: >- Whether the wallet is hosted by a Virtual Asset Service Provider (VASP) or self-hosted. enum: - hosted - self_hosted vaspId: type: string format: uuid description: >- Identifier of the VASP that hosts the wallet. Required when `type` is `hosted`. Must not be set when `type` is `self_hosted`. example: 550e8400-e29b-41d4-a716-446655440000 AddressBookRecipientResponseGeneral: type: object properties: id: $ref: '#/components/schemas/Id' chain: $ref: '#/components/schemas/Chain' address: $ref: '#/components/schemas/Address' addressTag: $ref: '#/components/schemas/AddressTag' metadata: $ref: '#/components/schemas/AddressBookRecipientMetadata' status: type: string description: Status of the address book recipient. enum: - pending - inactive - active - denied AddressBookRecipientIdentityResponse: type: object description: > Beneficiary identity for the address book entry. When `type` is `individual`, include `firstName` and `lastName`. When `type` is `business`, include `businessName`. Related validation error codes include `2024` (identity missing), `2031`–`2034`, and `2036` (identity cannot be updated via PATCH). properties: type: type: string description: Whether the beneficiary is an individual or a business. enum: - individual - business firstName: type: string description: Required when `type` is `individual`. example: Ada lastName: type: string description: Required when `type` is `individual`. example: Lovelace businessName: type: string description: Legal business name. Required when `type` is `business`. example: Example Corp UtcTimestamp: type: string description: ISO-8601 UTC date/time format. example: '2020-04-10T02:13:30.000Z' AddressBookRecipientOwnershipResponse: type: object description: > Ownership and custody of the wallet for Travel Rule and compliance. Validation errors can include codes such as `2025` (ownership missing), `2026` (VASP ID missing when required), `2027`–`2030`, `2035` (VASP ID not allowed when custody is `self_hosted`), and `2037` (ownership cannot be updated via PATCH). properties: type: type: string description: Whether the wallet is first-party or third-party. enum: - first_party - third_party custody: $ref: '#/components/schemas/AddressBookRecipientCustodyResponse' Email: type: string description: Email of the user. maxLength: 1024 example: satoshi@circle.com LegalEntityIdentifier: type: string description: > Optional. Legal entity identifier (LEI). Unique global identifier for legal entities. Primarily relevant for French (CIRCLE_FR) entities. example: 529900T8BM49AURSDO55 Id: type: string description: Unique system generated identifier for the entity. format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 Chain: type: string description: > A blockchain that a given currency is available on. **Note:** Arc (`ARC`) is only available in the sandbox environment (`api-sandbox.circle.com`). enum: - ALGO - APTOS - ARB - ARC - AVAX - BASE - BTC - CELO - CODEX - ETH - HBAR - HYPEREVM - INK - LINEA - NEAR - NOBLE - OP - PLUME - PAH - POLY - SEI - SOL - SONIC - SUI - UNI - WORLDCHAIN - XDC - XLM - XRP - ZKS - ZKSYNC AddressBookRecipientCustodyResponse: type: object description: > Wallet custody details. When `type` is `hosted`, `vaspId` is required and must match an identifier returned by `GET /v1/addressBook/vasps`. When `type` is `self_hosted`, do not send `vaspId`. properties: type: type: string description: >- Whether the wallet is hosted by a Virtual Asset Service Provider (VASP) or self-hosted. enum: - hosted - self_hosted vaspId: type: string format: uuid description: >- Identifier of the VASP that hosts the wallet. Required when `type` is `hosted`. Must not be set when `type` is `self_hosted`. example: 550e8400-e29b-41d4-a716-446655440000 headers: XRequestId: description: >- Universally unique identifier (UUID v4) for the request. Helpful for identifying a request when communicating with Circle support. schema: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde responses: BadRequest: description: The request cannot be processed due to a client error. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: type: object title: BadRequest required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 400 message: Bad request. examples: response: value: code: 400 message: Bad request. NotAuthorized: description: >- The request has not been applied because it lacks valid authentication credentials. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: type: object title: NotAuthorized required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 401 message: Malformed authorization. examples: response: value: code: 401 message: Malformed authorization. securitySchemes: bearerAuth: type: http scheme: bearer ````