v2

Beneficiaries
Beneficiaries Endpoints

>>>

GET /beneficiaries?page=&per=&investor_id=
List of beneficiaries

Params

Param name Description
page
optional

Page index

Validations:

  • Must be a Integer
per
optional

Items per page

Validations:

  • Must be a Integer
investor_id
optional

Filter by investor UUID

Validations:

  • Must be a String

Examples

{
  'data': [
    {
  'id': 'beneficiary-uuid',
  'name': 'Nombre',
  'lastname': 'Apellido Paterno',
  'matriname': 'Apellido Materno',
  'nationality': null,
  'translated_nationality': null,
  'national_id_number': null,
  'phone_number': null,
  'phone_number_extension': null,
  'mobile_number': '5512345678',
  'dob': null,
  'email': 'ejemplo@correo.com',
  'kinship': 'spouse',
  'street': 'Av. Insurgentes Sur',
  'street_number': '453',
  'street_number_internal': null,
  'zip_code': '06600',
  'suburb': 'Hipódromo',
  'city': 'Ciudad de México',
  'state': 'CDMX',
  'country': 'MEX',
  'investor': {
    'id': 'investor-uuid',
    'sequential_id': 1,
    'code': null,
    'comment': null,
    'name': 'Nombre',
    'lastname': 'Apellido',
    'matriname': 'Materno',
    'full_name': 'Nombre Apellido Materno',
    'company': false,
    'company_name': null,
    'person_type': 'Persona física',
    'nationality': 'mexican',
    'translated_nationality': 'mexicano',
    'national_id_number': null,
    'phone_number': null,
    'phone_number_extension': null,
    'mobile_number': '5512345678',
    'gender': 'male',
    'dob': null,
    'human_readable_dob': null,
    'email': 'inversor@correo.com',
    'admission_date': '2024-01-15',
    'balance': { 'mxn': '500000.00', 'usd': '0.00' },
    'active_investment_amount': 1,
    'promoter_id': 'promoter-uuid',
    'created_at': '2024-01-15 - 10:00',
    'updated_at': '2025-01-01 - 09:00',
    'created_by_full_name': 'Administrador',
    'country': null,
    'country_translated': null,
    'is_financial_entity': false,
    'prospect_id': null,
    'user_id': null,
    'user_created': false,
    'document_type': null,
    'document_number': null,
    'marital_status': null,
    'account_statement_password': null,
    'access_keys_sent': false,
    'extra_fields_attributes': [],
    'subsidiary_id': null,
    'subsidiary_name': null,
    'deletable': false
  }
}
  ],
  'meta': {
    'count': 1
  }
}

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
>>>

GET /beneficiaries/:id
Specific beneficiary

Params

Param name Description
id
required

Beneficiary UUID

Validations:

  • Must be a String

Examples

{
  'data': {
  'id': 'beneficiary-uuid',
  'name': 'Nombre',
  'lastname': 'Apellido Paterno',
  'matriname': 'Apellido Materno',
  'nationality': null,
  'translated_nationality': null,
  'national_id_number': null,
  'phone_number': null,
  'phone_number_extension': null,
  'mobile_number': '5512345678',
  'dob': null,
  'email': 'ejemplo@correo.com',
  'kinship': 'spouse',
  'street': 'Av. Insurgentes Sur',
  'street_number': '453',
  'street_number_internal': null,
  'zip_code': '06600',
  'suburb': 'Hipódromo',
  'city': 'Ciudad de México',
  'state': 'CDMX',
  'country': 'MEX',
  'investor': {
    'id': 'investor-uuid',
    'sequential_id': 1,
    'code': null,
    'comment': null,
    'name': 'Nombre',
    'lastname': 'Apellido',
    'matriname': 'Materno',
    'full_name': 'Nombre Apellido Materno',
    'company': false,
    'company_name': null,
    'person_type': 'Persona física',
    'nationality': 'mexican',
    'translated_nationality': 'mexicano',
    'national_id_number': null,
    'phone_number': null,
    'phone_number_extension': null,
    'mobile_number': '5512345678',
    'gender': 'male',
    'dob': null,
    'human_readable_dob': null,
    'email': 'inversor@correo.com',
    'admission_date': '2024-01-15',
    'balance': { 'mxn': '500000.00', 'usd': '0.00' },
    'active_investment_amount': 1,
    'promoter_id': 'promoter-uuid',
    'created_at': '2024-01-15 - 10:00',
    'updated_at': '2025-01-01 - 09:00',
    'created_by_full_name': 'Administrador',
    'country': null,
    'country_translated': null,
    'is_financial_entity': false,
    'prospect_id': null,
    'user_id': null,
    'user_created': false,
    'document_type': null,
    'document_number': null,
    'marital_status': null,
    'account_statement_password': null,
    'access_keys_sent': false,
    'extra_fields_attributes': [],
    'subsidiary_id': null,
    'subsidiary_name': null,
    'deletable': false
  }
}
}

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
>>>

POST /beneficiaries
Create a new beneficiary

Params

Param name Description
beneficiary
required

Beneficiary attributes

Validations:

  • Must be a Hash
beneficiary[name]
required

First name

Validations:

  • Must be a String
beneficiary[lastname]
required

Last name

Validations:

  • Must be a String
beneficiary[matriname]
optional

Second last name

Validations:

  • Must be a String
beneficiary[dob]
optional

Date of birth (YYYY-MM-DD)

Validations:

  • Must be a String
beneficiary[email]
optional

Email address

Validations:

  • Must be a String
beneficiary[nationality]
optional

Nationality key (e.g. mexican)

Validations:

  • Must be a String
beneficiary[national_id_number]
optional

CURP or national ID number

Validations:

  • Must be a String
beneficiary[phone_number]
optional

Phone number

Validations:

  • Must be a String
beneficiary[phone_number_extension]
optional

Phone extension

Validations:

  • Must be a String
beneficiary[mobile_number]
optional

Mobile number

Validations:

  • Must be a String
beneficiary[investor_id]
required

Associated investor UUID

Validations:

  • Must be a String
beneficiary[kinship]
optional

Kinship relationship (e.g. spouse, child, parent)

Validations:

  • Must be a String
beneficiary[street]
optional

Street name

Validations:

  • Must be a String
beneficiary[street_number]
optional

Street number

Validations:

  • Must be a String
beneficiary[street_number_internal]
optional

Interior unit number

Validations:

  • Must be a String
beneficiary[zip_code]
optional

ZIP / postal code

Validations:

  • Must be a String
beneficiary[suburb]
optional

Suburb / neighborhood

Validations:

  • Must be a String
beneficiary[city]
optional

City

Validations:

  • Must be a String
beneficiary[state]
optional

State / province

Validations:

  • Must be a String
beneficiary[country]
optional

Country code (e.g. MEX)

Validations:

  • Must be a String

Examples

# Request body:
{
  'beneficiary': {
    'name': 'Juan',
    'lastname': 'Perez',
    'matriname': 'Torres',
    'dob': '1985-06-20',
    'email': 'ejemplo@correo.com',
    'nationality': 'mexican',
    'phone_number': '5512345678',
    'mobile_number': '5598765432',
    'investor_id': 'investor-uuid',
    'kinship': 'spouse',
    'street': 'Av. Insurgentes Sur',
    'street_number': '453',
    'zip_code': '06600',
    'suburb': 'Hipódromo',
    'city': 'Ciudad de México',
    'state': 'CDMX',
    'country': 'MEX'
  }
}

# Response (201 Created): same structure as GET /beneficiaries/:id

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
>>>

PUT /beneficiaries/:id
Update an existing beneficiary

Params

Param name Description
id
required

Beneficiary UUID

Validations:

  • Must be a String
beneficiary
required

Beneficiary attributes to update

Validations:

  • Must be a Hash
beneficiary[name]
optional

First name

Validations:

  • Must be a String
beneficiary[lastname]
optional

Last name

Validations:

  • Must be a String
beneficiary[matriname]
optional

Second last name

Validations:

  • Must be a String
beneficiary[dob]
optional

Date of birth (YYYY-MM-DD)

Validations:

  • Must be a String
beneficiary[email]
optional

Email address

Validations:

  • Must be a String
beneficiary[nationality]
optional

Nationality key (e.g. mexican)

Validations:

  • Must be a String
beneficiary[national_id_number]
optional

CURP or national ID number

Validations:

  • Must be a String
beneficiary[phone_number]
optional

Phone number

Validations:

  • Must be a String
beneficiary[phone_number_extension]
optional

Phone extension

Validations:

  • Must be a String
beneficiary[mobile_number]
optional

Mobile number

Validations:

  • Must be a String
beneficiary[investor_id]
optional

Associated investor UUID

Validations:

  • Must be a String
beneficiary[kinship]
optional

Kinship relationship

Validations:

  • Must be a String
beneficiary[street]
optional

Street name

Validations:

  • Must be a String
beneficiary[street_number]
optional

Street number

Validations:

  • Must be a String
beneficiary[street_number_internal]
optional

Interior unit number

Validations:

  • Must be a String
beneficiary[zip_code]
optional

ZIP / postal code

Validations:

  • Must be a String
beneficiary[suburb]
optional

Suburb / neighborhood

Validations:

  • Must be a String
beneficiary[city]
optional

City

Validations:

  • Must be a String
beneficiary[state]
optional

State / province

Validations:

  • Must be a String
beneficiary[country]
optional

Country code (e.g. MEX)

Validations:

  • Must be a String

Examples

# Request body:
{
  'beneficiary': {
    'name': 'Nombre Actualizado',
    'kinship': 'child'
  }
}

# Response (200 OK): same structure as GET /beneficiaries/:id

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
>>>

DELETE /beneficiaries/:id
Delete a beneficiary

Params

Param name Description
id
required

Beneficiary UUID

Validations:

  • Must be a String

Examples

# Response (204 No Content) on success.
# Response (422 Unprocessable Entity) if the beneficiary cannot be deleted.

Errors

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error