> ## 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. For Singapore (CIRCLE_SG) customers creating a self-hosted (`ownership.custody.type` = `self_hosted`) entry, `metadata.email` is required and the beneficiary PII object matching `identity.type` (`identity.individual` or `identity.business`) is required. The two PII objects are mutually exclusive. For non-regulated jurisdictions the PII objects are accepted if provided but not required. Validation failures can return error codes in the `2024`–`2038` range (for example `2024` when `identity` is required but missing, `2025` when `ownership` is required but missing, `2038` when `metadata.email` is missing for a self-hosted entry), as well as the PII-missing errors `ADDRESS_BOOK_INDIVIDUAL_PII_MISSING` and `ADDRESS_BOOK_BUSINESS_PII_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. For Singapore (CIRCLE_SG) customers creating a self-hosted (`ownership.custody.type` = `self_hosted`) entry, `metadata.email` is required and the beneficiary PII object matching `identity.type` (`identity.individual` or `identity.business`) is required. The two PII objects are mutually exclusive. For non-regulated jurisdictions the PII objects are accepted if provided but not required. Validation failures can return error codes in the `2024`–`2038` range (for example `2024` when `identity` is required but missing, `2025` when `ownership` is required but missing, `2038` when `metadata.email` is missing for a self-hosted entry), as well as the PII-missing errors `ADDRESS_BOOK_INDIVIDUAL_PII_MISSING` and `ADDRESS_BOOK_BUSINESS_PII_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: FR customers description: >- For France (CIRCLE_FR) entities. Supports the optional `identity.lei` field. allOf: - $ref: '#/components/schemas/AddressBookRecipientRequestFr' - 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' frCustomers: summary: FR customers description: >- For France (CIRCLE_FR) entities. Supports the optional `identity.lei` field. 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: business businessName: Example Corp lei: 529900T8BM49AURSDO55 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' sgCustomersSelfHostedIndividual: summary: SG customers — self-hosted individual with PII description: >- For Singapore (CIRCLE_SG) entities creating a self-hosted entry for an individual beneficiary. `governmentIssuedId` is not returned. value: data: id: a8f3c2d1-0000-0000-0000-000000000000 chain: ETH address: '0x742d35Cc6634C0532925a3b844Bc9e7595f00000' metadata: nickname: John Doe email: john.doe@example.com status: pending identity: type: individual firstName: John lastName: Doe individual: dateOfBirth: '1990-01-15' nationality: SG addressLine1: 1 Marina Boulevard addressLine2: '#10-01' city: Singapore district: Central postalCode: 18989 country: SG ownership: type: third_party custody: type: self_hosted createDate: '2026-02-25T12:00:00.000Z' updateDate: '2026-02-25T12:00:00.000Z' sgCustomersSelfHostedBusiness: summary: SG customers — self-hosted business with PII description: >- For Singapore (CIRCLE_SG) entities creating a self-hosted entry for a business beneficiary. `businessRegistrationNumber`, `dateOfIncorporation`, and `businessIdentificationNumber` are not returned. value: data: id: a8f3c2d1-1111-1111-1111-111111111111 chain: ETH address: '0x742d35Cc6634C0532925a3b844Bc9e7595f00000' metadata: nickname: Acme Treasury email: treasury@acme.com status: pending identity: type: business businessName: Acme Corporation business: addressLine1: 8 Shenton Way addressLine2: Level 45 city: Singapore district: Downtown Core postalCode: 68811 country: SG countryOfIncorporation: SG ownership: type: third_party custody: type: self_hosted createDate: '2026-02-25T12:00:00.000Z' updateDate: '2026-02-25T12:00:00.000Z' '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' AddressBookRecipientRequestFr: allOf: - $ref: '#/components/schemas/AddressBookRecipientRequestBase' - type: object properties: identity: $ref: '#/components/schemas/AddressBookRecipientIdentityFr' 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`. Beneficiary Personally Identifiable Information (PII) required for MAS Travel Rule compliance on self-hosted wallet payouts is carried in the nested `individual` and `business` objects. These two child objects are mutually exclusive — at most one may be provided, and it must match `type`. For Singapore (CIRCLE_SG) customers creating a self-hosted (`ownership.custody.type` = `self_hosted`) entry the child object matching `type` is required; for non-regulated jurisdictions it is accepted if provided but not required. Name fields stay at this level and are not duplicated inside the child objects. Related validation error codes include `2024` (identity missing), `2031`–`2034`, `2036` (identity cannot be updated via PATCH), and the PII-missing errors `ADDRESS_BOOK_INDIVIDUAL_PII_MISSING` and `ADDRESS_BOOK_BUSINESS_PII_MISSING`. 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 individual: $ref: '#/components/schemas/AddressBookRecipientIndividualIdentity' business: $ref: '#/components/schemas/AddressBookRecipientBusinessIdentity' 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: FR customers description: >- For France (CIRCLE_FR) entities. Includes the optional `identity.lei` field. allOf: - $ref: '#/components/schemas/AddressBookRecipientResponseGeneral' - type: object properties: identity: $ref: '#/components/schemas/AddressBookRecipientIdentityResponseFr' 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' AddressBookRecipientIdentityFr: allOf: - $ref: '#/components/schemas/AddressBookRecipientIdentity' - type: object properties: lei: $ref: '#/components/schemas/LegalEntityIdentifier' 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 description: > Recipient metadata. For Singapore (CIRCLE_SG) customers creating a self-hosted (`ownership.custody.type` = `self_hosted`) entry, `email` is required (validation error `2038`). properties: nickname: type: string description: Nickname related to the address. example: sample nickname email: allOf: - $ref: '#/components/schemas/Email' - description: >- Email address of the recipient. Required for Singapore (CIRCLE_SG) self-hosted entries. bns: type: string description: Blockchain Name Service (e.g. ENS) domain for the address. example: sample.circle AddressBookRecipientIndividualIdentity: type: object description: > Beneficiary Personally Identifiable Information (PII) for an individual. Provided inside `identity` and mutually exclusive with `business`. Required for Singapore (CIRCLE_SG) customers creating a self-hosted (`ownership.custody.type` = `self_hosted`) entry when `identity.type` is `individual`. For non-regulated jurisdictions the fields are accepted if provided but not required. When this object is present, every field is required except `addressLine2`. Name fields stay at the `identity` level (`firstName`, `lastName`) and are not duplicated here. required: - dateOfBirth - nationality - addressLine1 - city - district - postalCode - country - governmentIssuedId properties: dateOfBirth: type: string description: Beneficiary's date of birth. pattern: ^\d{4}-\d{2}-\d{2}$ example: '1990-01-15' nationality: type: string description: >- Beneficiary's nationality. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. example: SG addressLine1: type: string description: Residential address, line 1. maxLength: 1024 example: 1 Marina Boulevard addressLine2: type: string description: Residential address, line 2 (optional). maxLength: 1024 example: '#10-01' city: type: string description: City. maxLength: 1024 example: Singapore district: type: string description: >- State / province / district. If the country is US or Canada, then this should use the two-letter code for the subdivision. maxLength: 1024 example: Central postalCode: type: string description: Postal / ZIP code. maxLength: 16 example: 18989 country: type: string description: >- Country of residence. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. maxLength: 2 example: SG governmentIssuedId: type: string description: >- Government-issued identification number (e.g. national ID / passport). Not returned in responses. maxLength: 1024 example: S1234567A AddressBookRecipientBusinessIdentity: type: object description: > Beneficiary Personally Identifiable Information (PII) for a business. Provided inside `identity` and mutually exclusive with `individual`. Required for Singapore (CIRCLE_SG) customers creating a self-hosted (`ownership.custody.type` = `self_hosted`) entry when `identity.type` is `business`. For non-regulated jurisdictions the fields are accepted if provided but not required. When this object is present, every field is required except `addressLine2`. The legal business name stays at the `identity` level (`businessName`) and is not duplicated here. required: - addressLine1 - city - district - postalCode - country - businessRegistrationNumber - dateOfIncorporation - countryOfIncorporation - businessIdentificationNumber properties: addressLine1: type: string description: Registered business address, line 1. maxLength: 1024 example: 8 Shenton Way addressLine2: type: string description: Registered business address, line 2 (optional). maxLength: 1024 example: Level 45 city: type: string description: City. maxLength: 1024 example: Singapore district: type: string description: >- State / province / district. If the country is US or Canada, then this should use the two-letter code for the subdivision. maxLength: 1024 example: Downtown Core postalCode: type: string description: Postal / ZIP code. maxLength: 16 example: 68811 country: type: string description: >- Country. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. maxLength: 2 example: SG businessRegistrationNumber: type: string description: Business registration number (BRN). Not returned in responses. maxLength: 1024 example: 201912345A dateOfIncorporation: type: string description: Date the business was incorporated. Not returned in responses. pattern: ^\d{4}-\d{2}-\d{2}$ example: '2019-06-01' countryOfIncorporation: type: string description: >- Country of incorporation. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. maxLength: 2 example: SG businessIdentificationNumber: type: string description: Business identification number (BIN). Not returned in responses. maxLength: 1024 example: T19LL1234A 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`. When Beneficiary Personally Identifiable Information (PII) was submitted, the matching nested `individual` or `business` object is returned. A subset of submitted fields is never returned: for `individual`, `governmentIssuedId`; for `business`, `businessRegistrationNumber`, `dateOfIncorporation`, and `businessIdentificationNumber`. 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 individual: $ref: '#/components/schemas/AddressBookRecipientIndividualIdentityResponse' business: $ref: '#/components/schemas/AddressBookRecipientBusinessIdentityResponse' UtcTimestamp: type: string description: ISO-8601 UTC date/time format. example: '2020-04-10T02:13:30.000Z' AddressBookRecipientIdentityResponseFr: allOf: - $ref: '#/components/schemas/AddressBookRecipientIdentityResponse' - type: object properties: lei: $ref: '#/components/schemas/LegalEntityIdentifier' 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' LegalEntityIdentifier: type: string description: > Optional. Legal entity identifier (LEI). Unique global identifier for legal entities. Primarily relevant for French (CIRCLE_FR) entities. example: 529900T8BM49AURSDO55 Email: type: string description: Email of the user. maxLength: 1024 example: satoshi@circle.com 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 AddressBookRecipientIndividualIdentityResponse: type: object description: > Beneficiary Personally Identifiable Information (PII) for an individual, as returned in responses. `governmentIssuedId` is never returned. properties: dateOfBirth: type: string description: Beneficiary's date of birth. pattern: ^\d{4}-\d{2}-\d{2}$ example: '1990-01-15' nationality: type: string description: >- Beneficiary's nationality. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. example: SG addressLine1: type: string description: Residential address, line 1. maxLength: 1024 example: 1 Marina Boulevard addressLine2: type: string description: Residential address, line 2 (optional). maxLength: 1024 example: '#10-01' city: type: string description: City. maxLength: 1024 example: Singapore district: type: string description: State / province / district. maxLength: 1024 example: Central postalCode: type: string description: Postal / ZIP code. maxLength: 16 example: 18989 country: type: string description: >- Country of residence. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. maxLength: 2 example: SG AddressBookRecipientBusinessIdentityResponse: type: object description: > Beneficiary Personally Identifiable Information (PII) for a business, as returned in responses. `businessRegistrationNumber`, `dateOfIncorporation`, and `businessIdentificationNumber` are never returned. properties: addressLine1: type: string description: Registered business address, line 1. maxLength: 1024 example: 8 Shenton Way addressLine2: type: string description: Registered business address, line 2 (optional). maxLength: 1024 example: Level 45 city: type: string description: City. maxLength: 1024 example: Singapore district: type: string description: State / province / district. maxLength: 1024 example: Downtown Core postalCode: type: string description: Postal / ZIP code. maxLength: 16 example: 68811 country: type: string description: >- Country. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. maxLength: 2 example: SG countryOfIncorporation: type: string description: >- Country of incorporation. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2. maxLength: 2 example: SG 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 ````