Onboarding API

The Onboarding API allows managing the client onboarding process to the system. This includes registering new onboarding processes, uploading documents necessary for identity verification and validation, querying information related to ongoing processes, and managing master data such as economic activities.

Key Concepts

Onboarding Process: Set of steps and verifications necessary to onboard a new client to the system. Includes gathering personal, tax and regulatory information, as well as uploading and verifying documents.
Documents: Files (such as images or PDFs) that clients must provide to verify their identity and comply with regulatory requirements. Examples include ID, selfies and tax documents.
Master Tables: Catalogs and reference data used during the onboarding process, such as available economic activities.

Technical Specifications

Authentication

All API requests require authentication using a valid JWT token in the Authorization header with the format Bearer {token}.

Server

Base URL: https://api-dev.max.capital/onboarding/api

Versioning

The API uses URL versioning. The current version is v1, so all endpoints start with /v1/.

General Limits

Maximum file size for document upload: 5MB.
Request timeout: 30 seconds.

Endpoints

1. Register a new onboarding process

This endpoint allows creating a new onboarding process for a client. It is the entry point to start the onboarding.

Method	URL	Description
`POST`	`/v1/onboardings`	Registers a new onboarding process

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication (e.g. `Bearer {your-access-token}`)
`Content-Type`	Yes	Request content type (e.g. `application/json`)

Request Parameters

affiliation_id: Affiliation identifier (optional).
Request Body: A JSON object containing the necessary information for registering the onboarding process. This object must conform to the RegisterOnboardingDTO schema.

Request body example:

{
  "account": {
    "people": [
      {
        "type": "HUMAN",
        "ownership_type": "OWNER",
        "signature_type": "INDIVIDUAL",
        "personal_info": {
          "first_name": "Juan",
          "middle_name": "Carlos",
          "last_name": "Pérez",
          "second_last_name": "González",
          "document": {
            "type": "DNI_AR",
            "code": "28456789"
          },
          "gender": "MALE",
          "birth_date": "1982-05-15",
          "birth_country": "AR",
          "citizenship": "AR",
          "phone": "+5491156781234",
          "email": "[email protected]",
          "civil_status": {
            "type": "MARRIED",
            "spouse": {
              "name": "María",
              "surname": "López",
              "tax_document": {
                "type": "CUIT_AR",
                "code": "27301234569"
              }
            }
          }
        },
        "addresses": [
          {
            "type": "REAL",
            "street": "Av. Corrientes",
            "number": "1234",
            "floor": "5",
            "apartment": "A",
            "zip_code": "C1043AAZ",
            "city": "Buenos Aires",
            "state": "AR-C",
            "country": "AR"
          }
        ],
        "tax_info": {
          "document": {
            "type": "CUIT_AR",
            "code": "20284567890"
          },
          "income_tax_type": "NOT_REACHED",
          "value_added_tax_type": "NOT_REACHED",
          "is_obliged_subject": false,
          "gross_income_type": "NOT_APPLICABLE",
          "economic_activity": "43"
        }
      }
    ]
  }
}

Responses

201 Created: Onboarding process registered successfully. Returns an object with the process ID and other details.

Example:

{
  "id": 12345,
  "template": "DEFAULT",
  "account": {
    "type": "ACCOUNT_HOLDER",
    "number": 987654,
    "people": [
      {
        "id": 67890,
        "type": "HUMAN",
        "personalInfo": {
          "firstName": "Juan",
          "lastName": "Pérez",
          "documentType": "DNI_AR",
          "documentNumber": "28456789"
        }
      }
    ]
  }
}

400 Bad Request: Error in sent parameters.

Example:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "The 'account' parameter is required.",
  "errorCode": "VALIDATION_ERROR"
}

401 Unauthorized: Invalid or not provided authentication token.

Example:

{
  "statusCode": "401",
  "title": "Unauthorized",
  "detail": "Invalid or not provided authentication token.",
  "errorCode": "AUTH_ERROR"
}

500 Internal Server Error: Internal server error.

Example:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server.",
  "errorCode": "SERVER_ERROR"
}

Usage Example

curl -X POST 'https://api-dev.max.capital/onboarding/api/v1/onboardings' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: application/json' \
  -d '{
        "account": {
          "people": [
            {
              "type": "HUMAN",
              "ownership_type": "OWNER",
              "signature_type": "INDIVIDUAL",
              "personal_info": {
                "first_name": "Juan",
                "last_name": "Pérez",
                "document": {
                  "type": "DNI_AR",
                  "code": "28456789"
                },
                "gender": "MALE",
                "birth_date": "1982-05-15",
                "birth_country": "AR",
                "citizenship": "AR",
                "phone": "+5491156781234",
                "email": "[email protected]"
              },
              "addresses": [
                {
                  "type": "REAL",
                  "street": "Av. Corrientes",
                  "number": "1234",
                  "zip_code": "C1043AAZ",
                  "city": "Buenos Aires",
                  "state": "AR-C",
                  "country": "AR"
                }
              ],
              "tax_info": {
                "document": {
                  "type": "CUIT_AR",
                  "code": "20284567890"
                },
                "income_tax_type": "NOT_REACHED",
                "value_added_tax_type": "NOT_REACHED",
                "is_obliged_subject": false,
                "gross_income_type": "NOT_APPLICABLE",
                "economic_activity": "43"
              }
            }
          ]
        }
      }'

2. Upload documents for verification

This endpoint allows uploading documents necessary for the identity verification and validation process during onboarding.

Method	URL	Description
`POST`	`/v1/onboardings/{id}/person/{idPerson}/document`	Uploads a document for a specific person

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication (e.g. `Bearer {your-access-token}`)
`Content-Type`	Yes	Request content type (e.g. `multipart/form-data`)

URL Parameters

Parameter	Required	Description
`id`	Yes	Unique identifier of the onboarding process
`idPerson`	Yes	Unique identifier of the associated person

Query Parameters

Parameter	Required	Description
`documentType`	Yes	Document type (e.g. `DNI_FRENTE_AR`)
`status`	Yes	Initial document status (e.g. `PENDING`)
`expirationDate`	Yes	Expiration date in ISO 8601 format (e.g. `2025-12-31T13:43:48.000Z`)
`runOcr`	Yes	Indicates if OCR should be executed (`true`/`false`)

Request Body

A multipart/form-data file with the document (PDF, JPG, PNG).

Responses

200 OK: Document uploaded successfully. Returns the document ID.
- Example: 67890

400 Bad Request: Error in sent parameters.

Example:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "The 'documentType' parameter is required.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Onboarding process or person not found.

Example:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Onboarding process not found.",
  "errorCode": "NOT_FOUND"
}

413 Payload Too Large: File exceeds allowed size.

Example:

{
  "statusCode": "413",
  "title": "Payload Too Large",
  "detail": "File exceeds maximum allowed size of 5MB.",
  "errorCode": "FILE_TOO_LARGE"
}

500 Internal Server Error: Internal server error.

Example:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server.",
  "errorCode": "SERVER_ERROR"
}

Usage Example

curl -X POST 'https://api-dev.max.capital/onboarding/api/v1/onboardings/12345/person/67890/document?documentType=DNI_FRENTE_AR&status=PENDING&expirationDate=2025-12-31T13:43:48.000Z&runOcr=false' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/file/dni_front.jpg'

3. Query an onboarding process

This endpoint allows obtaining complete information of a specific onboarding process using its unique identifier.

Method	URL	Description
`GET`	`/v1/onboardings/{id}`	Queries an onboarding process by its ID

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication (e.g. `Bearer {your-access-token}`)

URL Parameters

Parameter	Required	Description
`id`	Yes	Unique identifier of the onboarding process

Responses

200 OK: Process information retrieved successfully.

Example:

{
  "id": 12345,
  "status": "PENDING",
  "account": {
    "number": 987654,
    "type": "ACCOUNT_HOLDER",
    "people": [
      {
        "id": 67890,
        "type": "HUMAN",
        "status": "PENDING",
        "personalInfo": {
          "firstName": "Juan",
          "lastName": "Pérez",
          "documentType": "DNI_AR",
          "documentNumber": "28456789"
        }
      }
    ]
  }
}

400 Bad Request: Error in sent parameters.

Example:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "The 'id' parameter must be a positive integer.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Onboarding process not found.

Example:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Onboarding process not found.",
  "errorCode": "NOT_FOUND"
}

500 Internal Server Error: Internal server error.

Example:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server.",
  "errorCode": "SERVER_ERROR"
}

Usage Example

curl -X GET 'https://api-dev.max.capital/onboarding/api/v1/onboardings/12345' \
  -H 'Authorization: Bearer {your-access-token}'

4. Get economic activities

This endpoint allows retrieving the complete catalog of economic activities available in the system.

Method	URL	Description
`GET`	`/v1/master-tables/economic-activities`	Gets the economic activities catalog

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication (e.g. `Bearer {your-access-token}`)

Responses

200 OK: Catalog retrieved successfully.

Example:

[
  {
    "idOption": "47",
    "description": "Employees in dependency relationship"
  },
  {
    "idOption": "620900",
    "description": "Other services related to informatics"
  }
]

400 Bad Request: Error in sent parameters.

Example:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "Invalid parameters in the request.",
  "errorCode": "VALIDATION_ERROR"
}

401 Unauthorized: Invalid or not provided authentication token.

Example:

{
  "statusCode": "401",
  "title": "Unauthorized",
  "detail": "Invalid or not provided authentication token.",
  "errorCode": "AUTH_ERROR"
}

500 Internal Server Error: Internal server error.

Example:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server.",
  "errorCode": "SERVER_ERROR"
}

Usage Example

curl -X GET 'https://api-dev.max.capital/onboarding/api/v1/master-tables/economic-activities' \
  -H 'Authorization: Bearer {your-access-token}'

5. Get document by ID

This endpoint allows retrieving complete information of a specific document using its unique identifier.

Method	URL	Description
`GET`	`/v1/documents/{id}`	Gets a document by its ID

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication (e.g. `Bearer {your-access-token}`)

URL Parameters

Parameter	Required	Description
`id`	Yes	Unique identifier of the document

Responses

200 OK: Document retrieved successfully.

Example:

{
  "id": 67890,
  "status": "PENDING",
  "documentType": "DNI_FRENTE_AR",
  "expirationDate": "2025-12-31"
}

400 Bad Request: Error in sent parameters.

Example:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "The 'id' parameter must be a positive integer.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Document not found.

Example:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Document not found.",
  "errorCode": "NOT_FOUND"
}

500 Internal Server Error: Internal server error.

Example:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server.",
  "errorCode": "SERVER_ERROR"
}

Usage Example

curl -X GET 'https://api-dev.max.capital/onboarding/api/v1/documents/67890' \
  -H 'Authorization: Bearer {your-access-token}'

6. Update document status

This endpoint allows updating the status of a specific document in the system.

Method	URL	Description
`PATCH`	`/v1/documents/{id}/status`	Updates the status of a document

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication (e.g. `Bearer {your-access-token}`)
`Content-Type`	Yes	Request content type (e.g. `application/json`)

URL Parameters

Parameter	Required	Description
`id`	Yes	Unique identifier of the document

Request Body

A JSON object with the new document status.

Request body example:

{
  "status": "APPROVED"
}

Responses

200 OK: Document status updated successfully.

Example:

{
  "id": 67890,
  "status": "APPROVED",
  "documentType": "DNI_FRENTE_AR",
  "expirationDate": "2025-12-31"
}

400 Bad Request: Error in sent parameters.

Example:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "The provided status is not valid.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Document not found.

Example:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Document not found.",
  "errorCode": "NOT_FOUND"
}

500 Internal Server Error: Internal server error.

Example:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server.",
  "errorCode": "SERVER_ERROR"
}

Usage Example

curl -X PATCH 'https://api-dev.max.capital/onboarding/api/v1/documents/67890/status' \
  -H 'Authorization: Bearer {your-access-token}' \
  -H 'Content-Type: application/json' \
  -d '{"status": "APPROVED"}'

7. Delete an onboarding process

This endpoint allows deleting a specific onboarding process from the system.

Method	URL	Description
`DELETE`	`/v1/onboardings/{id}`	Deletes an onboarding process by its ID

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication (e.g. `Bearer {your-access-token}`)

URL Parameters

Parameter	Required	Description
`id`	Yes	Unique identifier of the onboarding process

Responses

204 No Content: Onboarding process deleted successfully.

400 Bad Request: Error in sent parameters.

Example:

{
  "statusCode": "400",
  "title": "Bad Request",
  "detail": "The 'id' parameter must be a positive integer.",
  "errorCode": "VALIDATION_ERROR"
}

404 Not Found: Onboarding process not found.

Example:

{
  "statusCode": "404",
  "title": "Not Found",
  "detail": "Onboarding process not found.",
  "errorCode": "NOT_FOUND"
}

500 Internal Server Error: Internal server error.

Example:

{
  "statusCode": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server.",
  "errorCode": "SERVER_ERROR"
}

Usage Example

curl -X DELETE 'https://api-dev.max.capital/onboarding/api/v1/onboardings/12345' \
  -H 'Authorization: Bearer {your-access-token}'

Additional Notes

Authentication: All requests require a valid JWT token in the Authorization header.
Versioning: All endpoints belong to version v1 of the API, as indicated in the URL (/v1/).
Schemas: For a complete definition of the RegisterOnboardingDTO schema and others, consult the official schemas documentation in the API repository.
Error Handling: The API returns error responses in JSON format with a corresponding HTTP status code and error details.
Date Formats: All dates must be in ISO 8601 format (e.g. 2025-12-31T13:43:48.000Z).
Supported Document Types: Accepted document types include DNI_FRENTE_AR, DNI_DORSO_AR, SELFIE, among others, according to the system's master tables.

Key Concepts​

Technical Specifications​

Authentication​

Server​

Versioning​

General Limits​

Endpoints​

1. Register a new onboarding process​

Required Headers​

Request Parameters​

Responses​

Usage Example​

2. Upload documents for verification​

Required Headers​

URL Parameters​

Query Parameters​

Request Body​

Responses​

Usage Example​

3. Query an onboarding process​

Required Headers​

URL Parameters​

Responses​

Usage Example​

4. Get economic activities​

Required Headers​

Responses​

Usage Example​

5. Get document by ID​

Required Headers​

URL Parameters​

Responses​

Usage Example​

6. Update document status​

Required Headers​

URL Parameters​

Request Body​

Responses​

Usage Example​

7. Delete an onboarding process​

Required Headers​

URL Parameters​

Responses​

Usage Example​

Additional Notes​

Key Concepts

Technical Specifications

Authentication

Server

Versioning

General Limits

Endpoints

1. Register a new onboarding process

Required Headers

Request Parameters

Responses

Usage Example

2. Upload documents for verification

Required Headers

URL Parameters

Query Parameters

Request Body

Responses

Usage Example

3. Query an onboarding process

Required Headers

URL Parameters

Responses

Usage Example

4. Get economic activities

Required Headers

Responses

Usage Example

5. Get document by ID

Required Headers

URL Parameters

Responses

Usage Example

6. Update document status

Required Headers

URL Parameters

Request Body

Responses

Usage Example

7. Delete an onboarding process

Required Headers

URL Parameters

Responses

Usage Example

Additional Notes