Skip to content
API Reference/
Money Transfer
/
/Beneficiary

Beneficiary

This section provides the Beneficiary endpoints required to manage and operate the full lifecycle of resources within the ViaBlocks platform.

These endpoints are designed for secure, auditable, and scalable server-to-server integrations, and support core business operations and compliance workflows.

Operations

/beneficiary

Request

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.

Headers
x-client-idstring, [ 16 .. 64 ] charactersrequired

Unique identifier assigned to the integrating client.

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

Example:string
x-secret-keystring, [ 32 .. 128 ] charactersrequired

Secret authentication key associated with the client.

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

Example:string
Bodyapplication/jsonrequired
uuidstring, [ 10 .. 60 ] charactersrequired

UUID of the beneficiary to update.

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

firstNamestring, [ 2 .. 60 ] characters

Beneficiary's given name.

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

middleNamestring, [ 2 .. 60 ] characters

Beneficiary's middle name.

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

lastNamestring, [ 2 .. 60 ] characters

Beneficiary's primary family name.

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

secondLastNamestring, [ 2 .. 60 ] characters

Beneficiary's second family name.

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

phonestring, [ 10 .. 15 ] characters

Beneficiary's phone number without country code.

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

phoneCountryCodestring, [ 2 .. 4 ] characters

International dialing code.

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

emailstring, (email), [ 5 .. 60 ] characters

Beneficiary's email.

Error codes: type=400002, minLength=400003, maxLength=400004, format=400005

addressStreetstring, [ 2 .. 60 ] characters

Beneficiary address.

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

addressStreet2string, [ 2 .. 60 ] characters

Secondary address line.

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

addressCitystring, [ 2 .. 60 ] characters

City of residence.

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

addressCountrystring, [ 2 .. 3 ] characters

Country (ISO 3).

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

addressZipCodestring, [ 5 .. 6 ] characters

ZIP code.

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

relationShipstring, [ 2 .. 60 ] characters

Relationship between sender and beneficiary.

See Catalogs Endpoint RelationShips

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

documentTypestring, [ 2 .. 3 ] characters

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

documentNumberstring, [ 2 .. 60 ] characters

Identification document number of the beneficiary.

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

documentDescriptionstring, [ 2 .. 60 ] characters

Human-readable description of the identification document.

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

documentExpirationDatestring, [ 8 .. 10 ] characters

Expiration date of the beneficiary's identification document.

Format: YYYY-MM-DD

Error codes: type=400002, minLength=400003, maxLength=400004, format=400005

documentCountrystring, [ 2 .. 3 ] characters

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

POST
/beneficiary
curl -i -X POST \
  https://sandbox-viablocks.viamericas.io/beneficiary \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: string' \
  -H 'x-secret-key: string' \
  -d '{
    "senderUuid": "4ed19e29-5a6a-433d-908d-23377fabb617",
    "firstName": "ANGEL",
    "middleName": "",
    "lastName": "RESTADO",
    "secondLastName": "",
    "phone": "3057118816",
    "phoneCountryCode": "+1",
    "email": "angel@example.com",
    "addressStreet": "1450 Brickell Avenue Apt 2908, Miami, FL 33131, USA",
    "addressState": "US-FL",
    "addressCity": "MIAMI",
    "addressCountry": "USA",
    "addressZipCode": "33131",
    "relationShip": "Family"
  }'

Responses

Beneficiary created successfully.

Bodyapplication/json
statusstring

Result status (success).

messagestring

Confirmation message.

uuidstring

Unique identifier (UUID) of the created beneficiary.

Response
{
  "status": "success",
  "message": "Beneficiary created successfully",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}