Onboarding

Onboarding is the process by which you register your platform's users in API Broker, enabling a brokerage account for them to operate. It is a mandatory prerequisite for any module: Balance Remuneration, Mutual Funds, MEP Dollar, or Trading.

The flow is sequential and interdependent: each step generates an ID required by the next. Steps cannot be skipped.

General flow

POST /v2/persons
      ↓ person_id
POST /identity-documents (or /contracts for legal entities)
      ↓
POST /v2/investment-accounts
      ↓ investment_account_id
POST /bank-accounts
      ↓ bank_account_id

Step 1 — Person Registration

Endpoint

POST /api/accounts/v2/persons

The first step is to register the person in the system. Before starting, it is essential to distinguish the type:

• Individual (PF): a person with a national ID, date of birth, and personal data.
• Legal Entity (PJ): a legal entity (corporation, LLC, trust, etc.) with its own tax ID and company name.

This distinction determines which fields are required and what documentation will be requested in the next step.

Common fields (PF and PJ)

Individual-only fields (human_person)

Legal entity-only fields (legal_person)

Example body — Individual

{
  "persons": [{
    "job_activity_id": 10,
    "nationality_id": "AR",
    "country_document_id": "AR",
    "is_pep": false,
    "is_aml_cft_subject": false,
    "fatca_id": "",
    "oecd_identifiers": [],
    "tax_identifications": {
      "tax_identification_value": "20301234567",
      "residence_country_id": "AR",
      "tax_identification_type_id": "CUIL",
      "taxpayer_income_tax_type_id": "...",
      "vat_taxpayer_type_id": "...",
      "vat_country_taxpayer_type_id": "AR"
    },
    "human_person": {
      "surname": "García",
      "name": "Martín",
      "document_type_id": "DNI",
      "document_num": "30123456",
      "civil_status_id": "single",
      "birth_date": "1990-05-15",
      "birth_place": "Buenos Aires",
      "gender_id": "M",
      "signature": "base64string..."
    },
    "domiciles": [{
      "domicile_type_id": "real",
      "street": "Av. Corrientes",
      "house_number": 1234,
      "floor": 3,
      "apartment": "B",
      "country_id": "AR",
      "province_id": "BA",
      "zip_code": 1043,
      "location_id": 1
    }],
    "contact": {
      "email": "[email protected]",
      "mobile_phone": "+5491155667788"
    }
  }]
}

Example body — Legal Entity

{
  "persons": [{
    "job_activity_id": 50,
    "nationality_id": "AR",
    "country_document_id": "AR",
    "is_pep": false,
    "is_aml_cft_subject": false,
    "fatca_id": "",
    "oecd_identifiers": [],
    "tax_identifications": {
      "tax_identification_value": "30712345678",
      "residence_country_id": "AR",
      "tax_identification_type_id": "CUIT",
      "taxpayer_income_tax_type_id": "...",
      "vat_taxpayer_type_id": "...",
      "vat_country_taxpayer_type_id": "AR"
    },
    "legal_person": {
      "company_name": "Inversiones del Sur S.A.",
      "registration_number": "12345",
      "incorporation_place": "Buenos Aires",
      "country_id": "AR",
      "constitution_date": "2010-03-20",
      "book": "5",
      "volume": "10",
      "page": "123",
      "is_state_supplier": false,
      "corporate_type": 1
    },
    "domiciles": [{
      "domicile_type_id": "legal",
      "street": "Florida",
      "house_number": 500,
      "country_id": "AR",
      "province_id": "BA",
      "zip_code": 1005,
      "location_id": 1
    }],
    "contact": {
      "email": "[email protected]",
      "mobile_phone": "+541143210000"
    }
  }]
}

Response

{
  "items": [{
    "person_id": "F-9686d35b-b2e4-4f29-bb33-28bd73d12437",
    "surname": "García",
    "name": "Martín",
    "tax_identification_value": "20301234567",
    "error": null
  }]
}

Save the person_id. You will need it in all subsequent steps. If error is null, the registration was successful.

Step 2 — Documentation Upload

Individual — Identity documentation

POST /api/accounts/persons/identity-document

Three images are required in base64 format:

{
  "person_id": "F-9686d35b-b2e4-4f29-bb33-28bd73d12437",
  "front": "base64...",
  "back": "base64...",
  "face": "base64..."
}

If the individual is a PEP, they must also upload proof of source of funds (last 3 pay stubs, accounting certification, property deeds, etc.) using the /contracts endpoint with the pep_documents field.

Legal Entity — Corporate documentation

POST /api/accounts/persons/contracts

This endpoint uses multipart/form-data (not JSON). It allows sending files and text simultaneously.

What goes in each field by entity type?

Ultimate beneficial owner: you must identify all individuals with direct or indirect ownership of 10% or more. For example: if company A owns 50% of company B, and John owns 30% of A → John has 15% indirect ownership of B and must be declared.

Step 3 — Brokerage Account Creation

POST /api/accounts/v2/investment-accounts

Creates the user's investment account. Links the person_id obtained in step 1.

Required fields

The investment profile questionnaire has 5 questions. You can retrieve them at GET /api/master-tables/investor-questions. The system automatically calculates the resulting profile: conservative, moderate, or aggressive.

Example body

{
  "investment_accounts": [{
    "external_id": "client-123",
    "person_account_type_id": "human",
    "market_type": ["stock_market"],
    "investment_profile": {
      "1": 2,
      "2": 1,
      "3": 3,
      "4": 2,
      "5": 1
    },
    "owners": [{
      "person_id": "F-9686d35b-b2e4-4f29-bb33-28bd73d12437",
      "person_role_id": "holder"
    }]
  }]
}

Response

{
  "items": [{
    "external_id": "client-123",
    "investment_account_id": 43101,
    "investment_risk_profile": "moderate",
    "error": null
  }]
}

Save the investment_account_id. It is the central identifier used across all operational modules.

For legal entities: the system automatically generates a fund account in addition to the brokerage account. This enables the SIMPLE placement method for mutual funds.

Confirmation webhook

API Broker asynchronously notifies when the brokerage account and/or fund account has been created at the broker-dealer and/or the mutual fund management company:

Webhook: investment_account_update

Step 4 — Bank Account Registration

POST /api/accounts/bank-accounts/

Links a bank account to the brokerage account to enable deposits and withdrawals.

Fundamental rule: SAME NAME

The bank account must be held by the same owner as the brokerage account, verified by tax ID. Third-party accounts are not accepted.

Required fields

Example body

{
  "bank_accounts": [{
    "investment_account_id": 43101,
    "currency_id": "ARS",
    "cbu": "0000003100012345678901",
    "alias": "martin.garcia.mp"
  }]
}

Response

{
  "items": [{
    "investment_account_id": 43101,
    "cbu": "0000003100012345678901",
    "alias": "martin.garcia.mp",
    "bank_account_id": "ba-abc123",
    "error": null
  }]
}

You can register multiple bank accounts per brokerage account (e.g. one in ARS and one in USD) in a single call.

Key differences: Individual vs Legal Entity

Query endpoints

Once onboarding is complete, you can retrieve information with:

Key points to remember

1. Order is mandatory: a brokerage account cannot be created without a person_id, nor can a bank account be registered without an investment_account_id.
2. Save the IDs at each step: person_id, investment_account_id, and bank_account_id are the keys to all subsequent operations.
3. SAME NAME is non-negotiable: the bank account must be held by the same owner as the brokerage account, validated by tax ID.
4. Conditional PEP fields: if is_pep = true, the fields pep_relation and pep_position become mandatory.
5. Send FATCA and OECD as empty if not applicable: send "fatca_id": "" and "oecd_identifiers": [] rather than omitting them.
6. Legal entities automatically generate a fund account, which enables the SIMPLE method for mutual funds.
7. Always use v2 of the persons and brokerage account endpoints.
8. Always check the error field in the response. If it is not null, the registration failed and must be corrected before continuing.
9. Master table values (countries, provinces, document types, AFIP activity codes, etc.) must be retrieved beforehand from GET /api/master-tables/.