Clients API

This API allows managing clients in the system. It provides endpoints to create, read, update, and list clients, as well as perform specific operations such as updating the status and obtaining information about clients' credit lines.

The Client Object

The Client object represents a client in the system.

{
    "clientId": "b017d15b-68ed-4912-b026-ab2fbac80ad3",
    "partnerId": "79f7509e-4683-4ddc-98f2-fe631fa27652",
    "externalId": "cli:123",
    "status": "enabled",
    "legalName": "Abrego y Muñoz A.C.",
    "taxId": "20-44556677-8",
    "dba": "Pinturerías Muñoz",
    "address": "Av. Corrientes 1234, CABA",
    "emailAddress": "info@abregoymunios.com",
    "phoneNumber": "+5491112345678",
    "activationDate": "2021-01-01T00:00:00Z",
    "isEmailVerified": true,
    "isPhoneVerified": false,
    "createdAt": "2021-01-01T00:00:00Z",
    "updatedAt": "2021-01-01T00:00:00Z"
}

Attributes

Attribute	Description	Type
`clientId`	Unique identifier of the client	String (UUID)
`externalId`	Client identifier in the Partner's system	String
`legalName`	Legal name of the client registered in public records	String
`taxId`	Tax identification of the client	String
`dba`	Trade name or brand used by the client	String
`address`	Legal address of the client	String
`emailAddress`	Email address of the client	String
`phoneNumber`	Phone number of the client	String
`activationDate`	Activation date of the client	String (ISO 8601)
`partnerId`	Identifier of the Partner managing this client	String (UUID)
`status`	Client status (pending, enabled, disabled)	String
`isEmailVerified`	Indicates if the email has been verified	Boolean
`isPhoneVerified`	Indicates if the phone number has been verified	Boolean
`createdAt`	Date and time of client creation	String (ISO 8601)
`updatedAt`	Date and time of the last client update	String (ISO 8601)

Endpoints

Create a New Client

Creates a new client in the system.

POST /v2/clients

Input Parameters:

Parameter	Description	Type	Required
`externalId`	Client identifier in the Partner's system	String	Yes
`legalName`	Legal name of the client	String	Yes
`taxId`	Tax identification of the client	String	Yes
`dba`	Trade name or brand used by the client	String	Yes
`address`	Legal address of the client	String	Yes
`emailAddress`	Email address of the client	String	Yes
`phoneNumber`	Phone number of the client	String	No
`activationDate`	Activation date of the client	String	No
`partnerId`	Identifier of the Partner managing this client	String	No

Example Request:

{
    "externalId": "cli:123",
    "legalName": "Abrego y Muñoz A.C.",
    "taxId": "20-44556677-8",
    "dba": "Pinturerías Muñoz",
    "address": "Av. Corrientes 1234, CABA",
    "emailAddress": "info@abregoymunios.com",
    "phoneNumber": "+54 9 11 1234 5678",
    "activationDate": "2023-11-29",
    "partnerId": "79f7509e-4683-4ddc-98f2-fe631fa27652"
}

Successful Response: The response will be a complete Client object, as described above.

Get a Client

Retrieves information about a specific client.

GET /v2/clients/:clientId

Path Parameters:

Parameter	Description
`clientId`	ID of the client to get

Successful Response:

The response will be a complete Client object, as described above.

Update a Client

Updates information of an existing client.

PATCH /v2/clients/:clientId

Path Parameters:

Parameter	Description
`clientId`	ID of the client to update

Input Parameters:

Parameter	Description	Type
`emailAddress`	New email address of the client	String

Example Request:

{
    "emailAddress": "nuevo.email@abregoymunios.com"
}

Successful Response:

The response will be the updated Client object.

List Clients

Retrieves a paginated list of clients with filtering and sorting options.

GET /v2/clients

Query Parameters:

Parameter	Description	Type
`name`	Filter by client name	String
`email`	Filter by email	String
`partner`	Filter by partner ID	String
`status`	Filter by client status	String
`tax-id`	Filter by tax identification	String
`external-id`	Filter by external ID	String
`sort-by`	Field to sort by	String
`sort-direction`	Sorting direction (asc or desc)	String
`offset`	List offset	Integer
`limit`	Limit of items to return	Integer
`page`	Page number	Integer
`per-page`	Items per page	Integer

Successful Response:

[
    {
        "clientId": "b017d15b-68ed-4912-b026-ab2fbac80ad3",
        "partnerId": "79f7509e-4683-4ddc-98f2-fe631fa27652",
        "externalId": "cli:123",
        "status": "enabled",
        "legalName": "Abrego y Muñoz A.C.",
        "taxId": "20-44556677-8",
        "dba": "Pinturerías Muñoz",
        "address": "Av. Corrientes 1234, CABA",
        "emailAddress": "info@abregoymunios.com",
        "phoneNumber": "+5491112345678",
        "isEmailVerified": true,
        "isPhoneVerified": false,
        "createdAt": "2021-01-01T00:00:00Z",
        "updatedAt": "2021-01-01T00:00:00Z"
    }
]

The X-Total-Count response header carries the total unpaginated count.

Get Client Status

Retrieves a summary of the credit lines of a specific client.

GET /v2/clients/:clientId/status

Path Parameters:

Parameter	Description
`clientId`	ID of the client to query

Successful Response:

{
    "clientId": "b017d15b-68ed-4912-b026-ab2fbac80ad3",
    "externalId": "cli:123",
    "legalName": "Abrego y Muñoz A.C.",
    "taxId": "20-44556677-8",
    "partnerId": "79f7509e-4683-4ddc-98f2-fe631fa27652",
    "status": "enabled",
    "tenant": "altscore",
    "creditLines": {
        "bnpl": {
            "assigned": {
                "amount": "100000.00",
                "currency": "ARS"
            },
            "available": {
                "amount": "90000.00",
                "currency": "ARS"
            },
            "consumed": {
                "amount": "10000.00",
                "currency": "ARS"
            }
        },
        "dpa": {
            "assigned": {
                "amount": "100000.00",
                "currency": "ARS"
            },
            "available": {
                "amount": "90000.00",
                "currency": "ARS"
            },
            "consumed": {
                "amount": "10000.00",
                "currency": "ARS"
            }
        }
    }
}

Change Client Status

Updates the status of a specific client.

PUT /v2/clients/:clientId/status

Path Parameters:

Parameter	Description
`clientId`	ID of the client to update

Input Parameters:

Parameter	Description	Type
`status`	New status of the client (enabled, disabled)	String

Example Request:

{
    "status": "enabled"
}

Successful Response:

The response will be a ClientStatusResponse object, as shown in the previous example.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
404	Not Found
409	Conflict

Errors will include a descriptive message in the response body.

Credit Line Summary

The Client Summary endpoint provides comprehensive financial overviews for clients with active debts in the DPA system. It delivers real-time credit metrics (assigned, available, consumed amounts), debt information (active debt counts, total balances), and risk indicators (days past due, overdue debt counts, risk categories).

This endpoint enables partners to quickly assess client portfolio health, make informed credit decisions, and monitor risk exposure through detailed overdue balance breakdowns by component (interest, penalties, principal, taxes). Essential for credit management workflows and client financial monitoring.

Single Credit Line Summary

Will calculate and return a summary of a specific client's credit line.

GET /v2/clients/:clientId/summary

Path Parameters:

Parameter	Description
`clientId`	ID of the client

Successful Response:

{
  "client": {
    "borrowerId": "8d9b1f3e-2d8a-4f5b-8c6d-0a1b2c3d4e5f",
    "clientId": "7c9b1f3e-2d8a-4f5b-8c6d-0a1b2c3d4e5f",
    "email": "mcgiber@irepair.com,info@irepair.com",
    "externalId": "cli:32321",
    "legalName": "Frodo Baggins",
    "partnerId": "6457c3ce-3887-45d6-92ca-299219ea96db",
    "status": "active"
  },
  "summary": {
    "creditMetrics": {
      "assigned": {
        "amount": "10000.00",
        "currency": "MXN"
      },
      "available": {
        "amount": "10000.00",
        "currency": "MXN"
      },
      "consumed": {
        "amount": "10000.00",
        "currency": "MXN"
      },
      "utilizationPercentage": 65.5
    },
    "debtInformation": {
      "numberOfActiveDebts": 3,
      "overdueBalanceBreakdown": {
        "interest": {
          "amount": "10000.00",
          "currency": "MXN"
        },
        "penalties": {
          "amount": "10000.00",
          "currency": "MXN"
        },
        "principal": {
          "amount": "10000.00",
          "currency": "MXN"
        },
        "taxes": {
          "amount": "10000.00",
          "currency": "MXN"
        }
      },
      "totalCurrentBalance": {
        "amount": "10000.00",
        "currency": "MXN"
      },
      "totalDebtAmount": {
        "amount": "10000.00",
        "currency": "MXN"
      },
      "totalDueBalance": {
        "amount": "10000.00",
        "currency": "MXN"
      },
      "totalOverdueAmount": {
        "amount": "10000.00",
        "currency": "MXN"
      }
    },
    "riskIndicators": {
      "clientRiskCategory": "medium",
      "maxDaysPastDue": 45,
      "numberOfOverdueDebts": 1,
      "oldestOverdueDate": "2025-07-01"
    }
  }
}

Query Credit Line Summary

List credit line summaries for multiple clients with filtering and pagination options.

GET /v2/clients/summary

Path Parameters:

Parameter	Description
`clientId`	ID of the client to update

Query Parameters:

Parameter	Description	Type
`client-ids`	Filter by client IDs	String Array
`overdue-days-min`	Minimum number of overdue days	Number
`credit-line-status`	Filter by credit line status	String (pending, enabled, disabled)
`risk-category`	Filter by risk category	String (low, medium, high)
`page`	Page number	Integer
`per-page`	Items per page	Integer

Successful Response:

A list of ClientSummaryResponse objects, as shown in the previous example.

On this page