v2

Prospects
Prospects Endpoints

>>>

GET /prospects?page=&per=
List of Prospects

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': 'prospect-uuid',
      'sequential_id': 1,
      'name': 'Test',
      'lastname': 'Prospect',
      'matriname': 'Example',
      'full_name': 'Test Prospect Example',
      'company': false,
      'company_name': null,
      'person_type': 'Persona física',
      'email': 'prospect@example.com',
      'tentative_investment': {
        'mxn': '0.00',
        'usd': '0.00'
      },
      'max_status': 'En proceso',
      'phone_number': '5500000000',
      'phone_number_extension': '5500000000',
      'mobile_number': '5500000000',
      'gender': 'other',
      'dob': '1990-01-01',
      'contact_date': null,
      'street': null,
      'street_number': null,
      'street_number_internal': null,
      'postal_code': null,
      'city': null,
      'state': null,
      'country': null,
      'suburb': null,
      'created_at': '2026-04-30 - 10:00',
      'updated_at': '2026-04-30 - 12:00',
      'created_by_full_name': 'Name Example',
      'nationality': null,
      'translated_nationality': null,
      'commentary': 'Comment example',
      'promoter_id': 'promoter-uuid',
      'country_translated': null,
      'prospections': [
        {
          'id': 'prospections-uuid',
          'sequential_id': 1,
          'initial_amount': '1000000.00',
          'type_of': 'promissory_note',
          'status': 'in_process',
          'status_translated': 'En proceso',
          'start_date': '2026-04-01',
          'end_date': '2027-04-30',
          'currency': {
            'name': 'MXN',
            'value': 'mxn'
          },
          'interest_rate': '29.00',
          'includes_external_rate': false,
          'external_rate_label': null,
          'interest_rate_floor': null,
          'interest_rate_ceiling': null,
          'commentary': 'Test prospection commentary',
          'promoter': {
            'id': 'promoter-uuid',
            'full_name': 'Test Promoter'
          },
          'investor': null,
          'tentative_investment_mxn': '1000000.00',
          'tentative_investment_usd': 0,
          'promissory_duration_months': null,
          'minimum_term_months': null,
          'extra_fields_attributes': []
        }
      ],
      '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'
      }
    }
  ],
  'meta': {
    'count': 1
  }
}

Errors

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

GET /prospects/:id
Specific prospect

Params

Param name Description
id
required

Requested prospect ID

Validations:

  • Must be a String

Examples

{
  'data': {
    'id': 'prospect-uuid',
    'sequential_id': 1,
    'name': 'Name',
    'lastname': 'Example',
    'matriname': null,
    'full_name': 'Name Example',
    'company': false,
    'company_name': null,
    'person_type': 'Persona física',
    'email': 'prospect@example.com',
    'tentative_investment': {
      'mxn': '0.00',
      'usd': '0.00'
    },
    'max_status': 'En proceso',
    'phone_number': '5500000000',
    'phone_number_extension': '5551112233',
    'mobile_number': '5559998877',
    'gender': 'other',
    'dob': '1990-01-01',
    'contact_date': null,
    'street': null,
    'street_number': null,
    'street_number_internal': null,
    'postal_code': null,
    'city': null,
    'state': null,
    'country': null,
    'suburb': null,
    'created_at': '2026-01-01 - 10:00',
    'updated_at': '2026-01-02 - 12:00',
    'created_by_full_name': 'Test Admin',
    'nationality': 'test_nationality',
    'translated_nationality': 'Test Nationality',
    'commentary': 'Test commentary',
    'promoter_id': 'promoter-uuid',
    'country_translated': 'México',
    'prospections': [
      {
        'id': 'prospections-uuid',
        'sequential_id': 1,
        'initial_amount': '1000000.00',
        'type_of': 'promissory_note',
        'status': 'in_process',
        'status_translated': 'En proceso',
        'start_date': '2026-04-01',
        'end_date': '2027-04-30',
        'currency': {
          'name': 'MXN',
          'value': 'mxn'
        },
        'interest_rate': '29.00',
        'includes_external_rate': false,
        'external_rate_label': null,
        'interest_rate_floor': null,
        'interest_rate_ceiling': null,
        'commentary': 'Test prospection commentary',
        'promoter': {
          'id': 'promoter-uuid',
          'full_name': 'Test Promoter'
        },
        'investor': null,
        'tentative_investment_mxn': '1000000.00',
        'tentative_investment_usd': 0,
        'promissory_duration_months': null,
        'minimum_term_months': null,
        'extra_fields_attributes': []
      }
    ],
    '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'
    }
  }
}

Errors

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

GET /prospects/:id/prospections
Prospections from specific prospect

Params

Param name Description
id
required

Requested prospect ID

Validations:

  • Must be a String

Examples

{
  'data': [
    {
      'id': 'prospection-uuid',
      'sequential_id': 1,
      'initial_amount': '1000000.0',
      'type_of': 'promissory_note',
      'status': 'standby',
      'status_translated': 'En espera',
      'start_date': '2021-07-01',
      'end_date': '2022-07-01',
      'currency': 'mxn',
      'interest_rate': '12.0',
      'includes_external_rate': false,
      'external_rate_label': null,
      'interest_rate_floor': null,
      'interest_rate_ceiling': null,
      'commentary': 'Some notes',
      'investor_id': null,
      'prospect': { ... },
      'society': { ... },
      'organization': { ... }
    }
  ],
  'meta': {
    'count': 1
  }
}

Errors

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

POST /prospects
Create a new prospect

Params

Param name Description
prospect
required

Prospect attributes

Validations:

  • Must be a Hash
prospect[name]
required

First name

Validations:

  • Must be a String
prospect[lastname]
required

Last name

Validations:

  • Must be a String
prospect[matriname]
optional

Second last name

Validations:

  • Must be a String
prospect[company]
optional

Whether the prospect is a company

Validations:

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

Company name (required when company is true)

Validations:

  • Must be a String
prospect[email]
optional

Email address

Validations:

  • Must be a String
prospect[phone_number]
optional

Phone number

Validations:

  • Must be a String
prospect[phone_number_extension]
optional

Phone extension

Validations:

  • Must be a String
prospect[mobile_number]
optional

Mobile number

Validations:

  • Must be a String
prospect[gender]
optional

Gender

Validations:

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

Date of birth (YYYY-MM-DD)

Validations:

  • Must be a String
prospect[contact_date]
optional

Contact date (YYYY-MM-DD)

Validations:

  • Must be a String
prospect[nationality]
optional

Nationality key (e.g. mexican)

Validations:

  • Must be a String
prospect[promoter_id]
optional

Associated promoter UUID

Validations:

  • Must be a String
prospect[street]
optional

Street name

Validations:

  • Must be a String
prospect[street_number]
optional

Street number

Validations:

  • Must be a String
prospect[street_number_internal]
optional

Interior number

Validations:

  • Must be a String
prospect[postal_code]
optional

Postal code

Validations:

  • Must be a String
prospect[city]
optional

City

Validations:

  • Must be a String
prospect[state]
optional

State

Validations:

  • Must be a String
prospect[country]
optional

Country code

Validations:

  • Must be a String
prospect[suburb]
optional

Suburb / colony

Validations:

  • Must be a String
prospect[commentary]
optional

Additional notes

Validations:

  • Must be a String

Examples

# Request body:
{
  'prospect': {
    'name': 'Test',
    'lastname': 'Prospect',
    'email': 'test.prospect@example.com',
    'phone_number': '5512345678',
    'gender': 'male',
    'dob': '1990-06-15',
    'contact_date': '2026-05-07',
    'nationality': 'mexican',
    'promoter_id': 'promoter-uuid',
    'commentary': 'First contact via referral'
  }
}

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

Errors

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

PUT /prospects/:id
Update an existing prospect

Params

Param name Description
id
required

Prospect ID to update

Validations:

  • Must be a String
prospect
required

Prospect attributes to update

Validations:

  • Must be a Hash
prospect[name]
optional

First name

Validations:

  • Must be a String
prospect[lastname]
optional

Last name

Validations:

  • Must be a String
prospect[matriname]
optional

Second last name

Validations:

  • Must be a String
prospect[email]
optional

Email address

Validations:

  • Must be a String
prospect[phone_number]
optional

Phone number

Validations:

  • Must be a String
prospect[mobile_number]
optional

Mobile number

Validations:

  • Must be a String
prospect[gender]
optional

Gender

Validations:

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

Date of birth (YYYY-MM-DD)

Validations:

  • Must be a String
prospect[contact_date]
optional

Contact date (YYYY-MM-DD)

Validations:

  • Must be a String
prospect[nationality]
optional

Nationality key (e.g. mexican)

Validations:

  • Must be a String
prospect[promoter_id]
optional

Associated promoter UUID

Validations:

  • Must be a String
prospect[commentary]
optional

Additional notes

Validations:

  • Must be a String

Examples

# Request body:
{
  'prospect': {
    'commentary': 'Updated via API'
  }
}

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

Errors

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

DELETE /prospects/:id
Delete a prospect

Params

Param name Description
id
required

Prospect 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