v2

Promoters
Promoters Endpoints

>>>

GET /promoters?page=&per=
List of promoters

Params

Param name Description
page
optional

Page index

Validations:

  • Must be a Integer
per
optional

Items per page

Validations:

  • Must be a Integer

Examples

{
  'data': [
    {
      'id': 'promoter-uuid',
      'sequential_id': 1,
      'name': 'Test',
      'lastname': 'User',
      'matriname': 'Example',
      'full_name': 'Test User Example',
      'company': false,
      'company_name': null,
      'person_type': 'Persona física',
      'email': 'test@example.com',
      'phone_number': '5551234567',
      'phone_number_extension': null,
      'mobile_number': '5559876543',
      'gender': 'other',
      'dob': '1990-01-01',
      'tax_number': 'TAX123456',
      'base_commission': '2.00',
      'organization_id': 'org-uuid',
      'investors_attracted': 3,
      'nationality': 'test_nationality',
      'translated_nationality': 'Test Nationality',
      'active_investors_amount': {
        'mxn': '1000.00',
        'usd': '500.00'
      },
      'created_at': '2026-01-01 - 10:00',
      'updated_at': '2026-01-02 - 12:00',
      'created_by_full_name': 'Test Admin',
      'country': 'MEX',
      'country_translated': 'México',
      'is_financial_entity': false,
      'subsidiary_id': 'subsidiary-uuid',
      'extra_fields_attributes': [
        {
          'id': 'extra-field-uuid',
          'value': 'Test Value',
          'label': 'Test Label',
          'input_type': 'text',
          'options': ['Option 1', 'Option 2'],
          'key': 'key_TEST'
        }
      ],
      'subsidiary_name': 'Test Subsidiary'
    }
  ],
  'meta': {
    'count': 1
  }
}

Errors

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

GET /promoters/:id
Specific promoter

Params

Param name Description
id
required

Requested promoter ID

Validations:

  • Must be a String

Examples

{
  'data': {
    'id': 'promoter-uuid',
    'sequential_id': 1,
    'name': 'Test',
    'lastname': 'User',
    'matriname': 'Example',
    'full_name': 'Test User Example',
    'company': false,
    'company_name': null,
    'person_type': 'Persona física',
    'email': 'test@example.com',
    'phone_number': '5551234567',
    'phone_number_extension': null,
    'mobile_number': '5559876543',
    'gender': 'other',
    'dob': '1990-01-01',
    'tax_number': 'TAX123456',
    'base_commission': '2.00',
    'organization_id': 'org-uuid',
    'investors_attracted': 3,
    'nationality': 'test_nationality',
    'translated_nationality': 'Test Nationality',
    'active_investors_amount': {
      'mxn': '1000.00',
      'usd': '500.00'
    },
    'created_at': '2026-01-01 - 10:00',
    'updated_at': '2026-01-02 - 12:00',
    'created_by_full_name': 'Test Admin',
    'country': 'MEX',
    'country_translated': 'México',
    'is_financial_entity': false,
    'subsidiary_id': 'subsidiary-uuid',
    'extra_fields_attributes': [
      {
        'id': 'extra-field-uuid',
        'value': 'Test Value',
        'label': 'Test Label',
        'input_type': 'text',
        'options': ['Option 1', 'Option 2'],
        'key': 'key_TEST'
      }
    ],
    'subsidiary_name': 'Test Subsidiary'
  }
}

Errors

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

GET /promoters/:id/prospections
Prospections from specific promoter

Params

Param name Description
id
required

Requested promoter ID

Validations:

  • Must be a String

Examples

{
  'data': [
    {
      'id': 'prospection-uuid',
      'sequential_id': 1512,
      'name': 'Name',
      'lastname': 'Example',
      'matriname': null,
      'full_name': 'Name Example ',
      'company': false,
      'company_name': null,
      'person_type': 'Persona física',
      'email': 'example@email.com',
      'phone_number': '5500000000',
      'phone_number_extension': null,
      'mobile_number': '5500000000',
      'gender': 'male',
      'dob': '1999-07-07',
      'contact_date': '2021-07-01',
      'status': 'in_process',
      'status_translated': 'En proceso',
      'street': 'Street Name',
      'street_number': 12,
      'street_number_internal': null,
      'postal_code': '00000',
      'city': 'City Name',
      'state': 'State Name',
      'country': null,
      'suburb': null,
      'tentative_investment': {
        'mxn': 0
      },
      'tentative_rate': '12.00',
      'tentative_entry_date': null,
      'tentative_currency': 'mxn',
      'nationality': null,
      'promoter_id': 'promoter-uuid',
      'country_translated': null,
      'prospections': [],
      'promoter': { ... }
    }
  ],
  'meta': {
    'count': 1
  }
}

Errors

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

GET /promoters/:id/investors
Investors from specific promoter

Also see investors#index.

Params

Param name Description
id
required

Requested promoter ID

Validations:

  • Must be a String

Examples

{
  'data': [
    {
      'id': 'investor-uuid',
      'sequential_id': 100,
      'code': 'INV100',
      'comment': 'Test comment',
      'name': 'Test',
      'lastname': 'Investor',
      'matriname': 'Example',
      'full_name': 'Test Investor Example',
      'company': false,
      'company_name': null,
      'person_type': 'Persona física',
      'nationality': 'test_nationality',
      'translated_nationality': 'Test Nationality',
      'national_id_number': 'NID123456',
      'phone_number': '5551112233',
      'phone_number_extension': null,
      'mobile_number': '5559998877',
      'gender': 'other',
      'dob': '1990-01-01',
      'human_readable_dob': 'lunes, 1 de enero de 1990',
      'email': 'investor@example.com',
      'admission_date': '2026-01-01',
      'balance': {
        'mxn': '5000.00',
        'usd': '250.00'
      },
      'active_investment_amount': 2,
      'promoter_id': 'promoter-uuid',
      'created_at': '2026-01-01 - 10:00',
      'updated_at': '2026-01-02 - 12:00',
      'created_by_full_name': 'Test Admin',
      'country': 'MEX',
      'country_translated': 'México',
      'is_financial_entity': false,
      'prospect_id': 'prospect-uuid',
      'user_created': true,
      'document_type': 'passport',
      'document_number': 'DOC123456',
      'marital_status': 'single',
      'account_statement_password': null,
      'access_keys_sent': false,
      'extra_fields_attributes': [
        {
          'id': 'extra-field-uuid',
          'value': 'Test Value',
          'label': 'Test Label',
          'input_type': 'text',
          'options': ['Option 1', 'Option 2'],
          'key': 'key_TEST'
        }
      ],
      'subsidiary_id': 'subsidiary-uuid',
      'subsidiary_name': 'Test Subsidiary',
      'promoter': {
        'id': 'promoter-uuid',
        'sequential_id': 1,
        'name': 'Test',
        'lastname': 'User',
        'matriname': 'Example',
        'full_name': 'Test User Example',
        'company': false,
        'company_name': null,
        'person_type': 'Persona física',
        'email': 'test@example.com',
        'phone_number': '5551234567',
        'phone_number_extension': null,
        'mobile_number': '5559876543',
        'gender': 'other',
        'dob': '1990-01-01',
        'tax_number': 'TAX123456',
        'base_commission': '2.00',
        'organization_id': 'org-uuid',
        'investors_attracted': 3,
        'nationality': 'test_nationality',
        'translated_nationality': 'Test Nationality',
        'active_investors_amount': {
          'mxn': '1000.00',
          'usd': '500.00'
        },
        'created_at': '2026-01-01 - 10:00',
        'updated_at': '2026-01-02 - 12:00',
        'created_by_full_name': 'Test Admin',
        'country': 'MEX',
        'country_translated': 'México',
        'is_financial_entity': false,
        'subsidiary_id': 'subsidiary-uuid',
        'extra_fields_attributes': [
          {
            'id': 'extra-field-uuid',
            'value': 'Test Value',
            'label': 'Test Label',
            'input_type': 'text',
            'options': ['Option 1', 'Option 2'],
            'key': 'key_TEST'
          }
        ],
        'subsidiary_name': 'Test Subsidiary'
      },
      'contacts': []
    }
  ],
  'meta': { 'count': 1 }
}

Errors

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

POST /promoters
Create a new promoter

Params

Param name Description
promoter
required

Promoter attributes

Validations:

  • Must be a Hash
promoter[name]
required

First name

Validations:

  • Must be a String
promoter[lastname]
required

Last name

Validations:

  • Must be a String
promoter[matriname]
optional

Second last name

Validations:

  • Must be a String
promoter[company]
optional

Whether the promoter is a company

Validations:

  • Must be one of: true, false, 1, 0.
promoter[company_name]
optional

Company name (required when company is true)

Validations:

  • Must be a String
promoter[email]
optional

Email address

Validations:

  • Must be a String
promoter[phone_number]
optional

Phone number

Validations:

  • Must be a String
promoter[phone_number_extension]
optional

Phone extension

Validations:

  • Must be a String
promoter[mobile_number]
optional

Mobile number

Validations:

  • Must be a String
promoter[gender]
optional

Gender

Validations:

  • Must be one of: male, female, other.
promoter[dob]
optional

Date of birth (YYYY-MM-DD)

Validations:

  • Must be a String
promoter[nationality]
optional

Nationality key (e.g. mexican)

Validations:

  • Must be a String
promoter[tax_number]
optional

RFC / tax number

Validations:

  • Must be a String
promoter[base_commission]
optional

Base commission percentage

Validations:

  • Must be a String
promoter[country]
optional

Country code

Validations:

  • Must be a String
promoter[subsidiary_id]
required

Associated subsidiary UUID (required)

Validations:

  • Must be a String
promoter[is_financial_entity]
optional

Whether the promoter is a financial entity

Validations:

  • Must be one of: true, false, 1, 0.

Examples

# Request body:
{
  'promoter': {
    'name': 'Test',
    'lastname': 'Ramirez',
    'matriname': 'Torres',
    'company': false,
    'email': 'test.ramirez@example.com',
    'mobile_number': '5591234567',
    'phone_number': '5512345678',
    'gender': 'male',
    'dob': '1980-06-15',
    'nationality': 'mexican',
    'tax_number': 'RATC800615ABC',
    'base_commission': '2.5',
    'country': 'MEX',
    'subsidiary_id': 'subsidiary-uuid',
    'is_financial_entity': false
  }
}

# Response (201 Created):
{
  'data': {
    'id': 'promoter-uuid',
    'sequential_id': 80,
    'name': 'Test',
    'lastname': 'Ramirez',
    'matriname': 'Torres',
    'full_name': 'Test Ramirez Torres',
    'company': false,
    'company_name': null,
    'person_type': 'Persona fisica',
    'email': 'test.ramirez@example.com',
    'phone_number': '5512345678',
    'mobile_number': '5591234567',
    'gender': 'male',
    'dob': '1980-06-15',
    'tax_number': 'RATC800615ABC',
    'base_commission': '2.5',
    'organization_id': 'org-uuid',
    'investors_attracted': 0,
    'nationality': 'mexican',
    'translated_nationality': 'mexicano',
    'active_investors_amount': { 'mxn': '0.00', 'usd': '0.00' },
    'country': 'mexico',
    'is_financial_entity': false,
    'subsidiary_id': 'subsidiary-uuid',
    'subsidiary_name': 'Terranova'
  }
}

Errors

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

PUT /promoters/:id
Update an existing promoter

Params

Param name Description
id
required

Promoter ID to update

Validations:

  • Must be a String
promoter
required

Promoter attributes to update

Validations:

  • Must be a Hash
promoter[name]
optional

First name

Validations:

  • Must be a String
promoter[lastname]
optional

Last name

Validations:

  • Must be a String
promoter[matriname]
optional

Second last name

Validations:

  • Must be a String
promoter[company]
optional

Whether the promoter is a company

Validations:

  • Must be one of: true, false, 1, 0.
promoter[company_name]
optional

Company name

Validations:

  • Must be a String
promoter[email]
optional

Email address

Validations:

  • Must be a String
promoter[phone_number]
optional

Phone number

Validations:

  • Must be a String
promoter[phone_number_extension]
optional

Phone extension

Validations:

  • Must be a String
promoter[mobile_number]
optional

Mobile number

Validations:

  • Must be a String
promoter[gender]
optional

Gender

Validations:

  • Must be one of: male, female, other.
promoter[dob]
optional

Date of birth (YYYY-MM-DD)

Validations:

  • Must be a String
promoter[nationality]
optional

Nationality key (e.g. mexican)

Validations:

  • Must be a String
promoter[tax_number]
optional

RFC / tax number

Validations:

  • Must be a String
promoter[base_commission]
optional

Base commission percentage

Validations:

  • Must be a String
promoter[country]
optional

Country code

Validations:

  • Must be a String
promoter[subsidiary_id]
optional

Associated subsidiary UUID

Validations:

  • Must be a String
promoter[is_financial_entity]
optional

Whether the promoter is a financial entity

Validations:

  • Must be one of: true, false, 1, 0.

Examples

# Request body:
{
  'promoter': {
    'email': 'test.updated@example.com',
    'base_commission': '3.0'
  }
}

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

Errors

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

DELETE /promoters/:id
Delete a promoter

Params

Param name Description
id
required

Promoter ID to delete

Validations:

  • Must be a String

Examples

# Response (204 No Content) on success.

Errors

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