# /beneficiary

Creates a new beneficiary (recipient) associated with a sender.
## Purpose
Registers a new beneficiary in the system, linking them to a sender. If a beneficiary with the same full name already exists for that sender, the existing record is returned instead of creating a duplicate.
## How It Works
1. Validates the request fields
2. Checks if a beneficiary with the same name already exists for the sender
3. If new, creates the beneficiary with a unique UUID
4. Returns the beneficiary UUID for use in transaction creation

## Important Notes
- A beneficiary can be shared across multiple senders
- The `senderUuid` field identifies which sender this beneficiary belongs to
- If the beneficiary already exists, the existing UUID is returned

## Authentication
Requires `x-client-id` and `x-secret-key` headers.

Endpoint: POST /beneficiary
Version: 1.0.0

## Header parameters:

  - `x-client-id` (string, required)
    Unique identifier assigned to the integrating client.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

  - `x-secret-key` (string, required)
    Secret authentication key associated with the client.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

## Request fields (application/json):

  - `uuid` (string, required)
    UUID of the beneficiary to update.
Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

  - `firstName` (string)
    Beneficiary's given name.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `middleName` (string)
    Beneficiary's middle name.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `lastName` (string)
    Beneficiary's primary family name.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `secondLastName` (string)
    Beneficiary's second family name.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `phone` (string)
    Beneficiary's phone number without country code.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `phoneCountryCode` (string)
    International dialing code.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `email` (string)
    Beneficiary's email.
Error codes: type=400002, minLength=400003, maxLength=400004, format=400005

  - `addressStreet` (string)
    Beneficiary address.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `addressStreet2` (string)
    Secondary address line.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `addressCity` (string)
    City of residence.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `addressCountry` (string)
    Country (ISO 3).
Error codes: type=400002, minLength=400003, maxLength=400004

  - `addressZipCode` (string)
    ZIP code.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `relationShip` (string)
    Relationship between sender and beneficiary.
See [Catalogs Endpoint RelationShips](/apis/outbound/catalogs/paths/~1catalogs~1recipients~1relationships/get)
Error codes: type=400002, minLength=400003, maxLength=400004

  - `documentType` (string)
    Type of identification document of the beneficiary.
You can check the types of documents available according to the beneficiary's country in our catalogs API:
Catalogs Endpoint Identifications: GET /catalogs/countries/{deliveryCountryISO}/identifications
Error codes: type=400002, minLength=400003, maxLength=400004

  - `documentNumber` (string)
    Identification document number of the beneficiary.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `documentDescription` (string)
    Human-readable description of the identification document.
Error codes: type=400002, minLength=400003, maxLength=400004

  - `documentExpirationDate` (string)
    Expiration date of the beneficiary's identification document.
Format: YYYY-MM-DD
Error codes: type=400002, minLength=400003, maxLength=400004, format=400005

  - `documentCountry` (string)
    Country that issued the beneficiary's identification document (ISO 3). https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
Error codes: type=400002, minLength=400003, maxLength=400004

## Response 200 fields (application/json):

  - `status` (string)
    Result status (`success`).

  - `message` (string)
    Confirmation message.

  - `uuid` (string)
    Unique identifier (UUID) of the created beneficiary.

## Response 400 fields (application/json):

  - `errors` (array)
    Error catalog for 400 (click to expand)CodeDescription400000Invalid JSON format in the request body.400001A required field is missing (senderUuid, firstName, lastName, etc.).400003Field does not meet minimum length requirement.400004Field exceeds maximum length.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)

## Response 401 fields (application/json):

  - `errors` (array)
    Error catalog for 401 (click to expand)CodeDescription401000Invalid credentials.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

## Response 404 fields (application/json):

  - `errors` (array)
    Error catalog for 404 (click to expand)CodeDescription404001Sender not found. The senderUuid does not match any existing sender.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)

## Response 422 fields (application/json):

  - `errors` (array)
    Error catalog for 422 (click to expand)CodeDescription422015A beneficiary with the same name already exists for this sender. The existing UUID is returned in the response.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)

  - `errors.uuid` (string)

## Response 500 fields (application/json):

  - `errors` (array)
    Error catalog for 500 (click to expand)CodeDescription500000Internal server error.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)