> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecleff.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a Beneficiary > Replaces the editable profile fields (name, alias, email, identity fields). Changing a PII trigger field (legal name, date of birth, country, tax id) on a compliant Beneficiary auto-raises reacknowledgment_required, blocking new Payouts until re-acknowledged. Identity-shape violations are rejected (422) with the row unchanged. ## OpenAPI ````yaml PUT /v1/beneficiaries/{id} openapi: 3.0.0 info: title: Cleff API description: >- Payout orchestration platform. All endpoints under /v1/ require an API key in the Authorization header (Bearer ck___). version: 0.0.1 contact: {} servers: [] security: [] tags: [] paths: /v1/beneficiaries/{id}: put: tags: - Beneficiaries summary: Edit a Beneficiary’s profile description: >- Replaces the editable profile fields (name, alias, email, identity fields). Changing a PII trigger field (legal name, date of birth, country, tax id) on a compliant Beneficiary auto-raises reacknowledgment_required, blocking new Payouts until re-acknowledged. Identity-shape violations are rejected (422) with the row unchanged. operationId: BeneficiariesController_update parameters: - name: id required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateBeneficiaryDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/BeneficiaryDto' '401': description: Missing or invalid credentials '404': description: Beneficiary not found security: - api_key: [] components: schemas: UpdateBeneficiaryDto: type: object properties: email: type: string format: email phone: type: string description: >- Optional contact phone. Non-trigger; full-replace (omitting clears it). nickname: type: string description: >- Cleff-only display label, preferred over the legal name. Non-trigger. first_name: type: string description: 'Person: given name (trigger field)' last_name: type: string description: 'Person: family name (trigger field)' country_of_residence: type: string description: 'Person: ISO 3166-1 alpha-2 country of residence (trigger)' date_of_birth: type: string description: 'Person: date of birth YYYY-MM-DD (trigger field)' business_name: type: string description: 'Business: legal business name (trigger field)' country_of_incorporation: type: string description: 'Business: ISO 3166-1 alpha-2 country of incorporation (trigger)' registration_number: type: string description: 'Business: Cleff-owned KYB record (trigger field)' tax_id: type: string description: Tax identifier (trigger field) postal_address: description: Optional mailing/legal address (omit to clear). Non-trigger. allOf: - $ref: '#/components/schemas/PostalAddressDto' required: - email BeneficiaryDto: type: object properties: id: type: string beneficiary_type: type: string enum: - person - business name: type: string description: Legal display name (first+last or business name); never piped nickname: type: object description: Business-facing display label, when set nullable: true display_name: type: string description: 'Preferred display label: nickname when set, else legal name' email: type: string phone: type: object nullable: true first_name: type: object nullable: true last_name: type: object nullable: true country_of_residence: type: object nullable: true date_of_birth: type: object nullable: true business_name: type: object nullable: true country_of_incorporation: type: object nullable: true registration_number: type: object nullable: true tax_id: type: object nullable: true postal_address: nullable: true description: Optional structured postal address; null when unset allOf: - $ref: '#/components/schemas/PostalAddressDto' bank_details: nullable: true deprecated: true allOf: - $ref: '#/components/schemas/BankDetailsDto' compliance_status: type: string enum: - pending - compliant - suspended identity_complete: type: boolean description: >- Derived: false while the per-type required identity field is still deferred (a stub in the awaiting_pii state). True once the identity is complete. Never stored. Computed against the CURRENT required-field list, so a compliant beneficiary can read false after that list grows: that is a top-up prompt, not a block — the beneficiary keeps its status and keeps receiving payouts, and supplying the field on PUT /v1/beneficiaries/:id or over a full_onboarding collect link flips it back to true. acknowledged_at: type: object format: date-time nullable: true reacknowledgment_required: type: boolean description: >- Soft flag: a trigger PII field changed after acknowledgment. Compliance status stays compliant, but new Payout creation is blocked until the Business re-acknowledges. collection_status: type: string enum: - not_invited - invited - details_submitted description: >- Identity collection sub-state. Only a full_onboarding link advances it — a bank_details link never touches the Beneficiary. details_submitted_at: type: object format: date-time nullable: true description: >- When the beneficiary completed the full_onboarding collection-link form. status: type: string enum: - suspended - reacknowledgment_required - pending_details - pending_kyc - action_required - ready description: >- Derived read-model Status chip: a pure projection over {identity completeness, compliance state + re-ack flag, bank-account validation/verification}. The `invited` chip was retired. Not a stored state machine. enrollment_status: type: string enum: - pending - verified - rejected - suspended - closed nullable: true description: >- Provider enrollment status for the default payout rail, or null when the Beneficiary has never been enrolled. `rejected` means the last synchronous enrollment attempt failed (e.g. the rail rejected the bank): the Beneficiary is compliant but payouts cannot reach them until re-enrollment succeeds. pending_requests: description: >- Derived: the beneficiary's live (unconsumed, unexpired) collection-link requests — `{id, scope, expires_at}` — read off the live-token store, never stored. Consumed/expired tokens never appear. Cardinality is 0..1 today (resend invalidates the prior link), but the shape is a list. type: array items: $ref: '#/components/schemas/PendingCollectionRequestDto' archived_at: type: object format: date-time nullable: true description: >- When the Business archived this Beneficiary, or null while it is active. An archived Beneficiary is gone from the address book (list, CSV export) and refuses new Payouts, but stays readable by id so a Payout's payee can still be resolved. environment: type: string enum: - sandbox - production created_at: type: string format: date-time required: - id - beneficiary_type - name - display_name - email - compliance_status - identity_complete - acknowledged_at - reacknowledgment_required - collection_status - details_submitted_at - status - pending_requests - archived_at - environment - created_at PostalAddressDto: type: object properties: line1: type: string description: Street address line 1 (required when an address is present) line2: type: string description: Street address line 2 (suite, unit, etc.) city: type: string description: City / locality (required when an address is present) state: type: string description: State / province / region postal_code: type: string description: Postal / ZIP code country: type: string description: >- ISO 3166-1 alpha-2 mailing country (required when an address is present) BankDetailsDto: type: object properties: account_holder_name: type: string country: type: string description: ISO 3166-1 alpha-2 of the bank country currency: type: string description: ISO 4217 currency code account_number: type: string description: Domestic account number (US/JP/etc.) routing_code: type: string description: US ABA, UK sort code, BR branch_code, etc. iban: type: string description: IBAN — required for European corridors swift_bic: type: string description: SWIFT/BIC — required for cross-border SWIFT routing bank_name: type: string required: - account_holder_name - country - currency PendingCollectionRequestDto: type: object properties: id: type: string format: uuid description: >- Collection-token id (safe to expose; the raw token is never serialized). scope: type: string enum: - full_onboarding - bank_details - tax_documents description: What the live link collects. expires_at: type: string format: date-time description: Token TTL expiry (7 days from mint). required: - id - scope - expires_at securitySchemes: api_key: scheme: bearer bearerFormat: ck___ type: http description: >- Cleff API key issued to a Business that self-registers via POST /v1/registration ````