Associates

Associates represent the customer's operators: drivers, distributors, paying students, guardians, club members. They are individuals tied to the customer's operations.

Model

{
  "id": 88,
  "type": "DRIVER",
  "name": "Operario",
  "lastName": "042",
  "taxId": "20999999999",
  "documentNumber": "99999999",
  "email": "[email protected]",
  "phone": "+541111000042",
  "address": "Av. Las Heras 2000, CABA",
  "parentAssociateId": null,
  "status": "ACTIVE",
  "creationDate": "2026-04-10T10:00:00-03:00",
  "modificationDate": "2026-04-10T10:00:00-03:00"
}

Field	Type	Required	Description
id	int64	(response)	ID assigned by Max Pay
type	string	Yes	Free-form type. Conventions: DRIVER, DISTRIBUTOR, STUDENT, GUARDIAN, MEMBER, OTHER
name	string	Yes	First name
lastName	string	Yes	Last name
taxId	string	Yes	CUIT/CUIL, 11 digits without dashes
documentNumber	string	Yes	DNI
email	string	Yes	Contact email
phone	string	Yes	Phone number with country code
address	string	No	Address
parentAssociateId	int64	No	For hierarchies (supervisor associate)
status	enum	(response)	ACTIVE or DISABLED

About the type field

type is a free-form string, not a closed enum. The customer can use any value that fits its business model. The recommended convention is uppercase values with underscores (DRIVER, GUARDIAN, STUDENT_PAYER, etc.). This makes it possible to add new types without breaking changes.

Endpoints

Method	Path	Description
GET	/v1/associates	List with filters
POST	/v1/associates	Create an associate
GET	/v1/associates/{id}	Detail
PUT	/v1/associates/{id}	Update
DELETE	/v1/associates/{id}	Disable (soft delete)
POST	/v1/associates/{id}/activations	Re-enable
GET	/v1/associates/{id}/receivable-accounts	Receivable accounts for the associate
GET	/v1/associates/{id}/route-settlements	Route settlements for the associate

Create an associate

POST /v1/associates
Idempotency-Key: erp-asc-12345
Content-Type: application/json

{
  "type": "DRIVER",
  "name": "Operario",
  "lastName": "042",
  "taxId": "20999999999",
  "documentNumber": "99999999",
  "email": "[email protected]",
  "phone": "+541111000042"
}

Creation does not create a receivable account

POST /v1/associates creates only the associate entity. If the associate needs their own receivable account (model B or C), it must be created separately with POST /v1/receivable-accounts. See How to create receivable accounts.

Response

201 Created
Location: /v1/associates/88

{
  "id": 88,
  "type": "DRIVER",
  ...
  "status": "ACTIVE",
  "creationDate": "2026-05-15T10:00:00-03:00"
}

Upsert by taxId

POST /v1/associates is also an upsert keyed by (customer, taxId). If an active associate with that taxId already exists for the customer, the response is 200 OK with the existing associate.

List filters

GET /v1/associates

Parameter	Type	Description
taxId	string	Exact CUIT/CUIL
documentNumber	string	Exact DNI
type	string	Specific type
parentAssociateId	int64	Associates that report to a parent
status	enum	Defaults to ACTIVE
ids	array of int64	List of specific IDs
page, count	int	Pagination

Disable

DELETE /v1/associates/88

204 No Content

This is a soft delete: the associate is set to status: DISABLED. Historical data remains accessible. Receivable accounts linked to this associate may become invalid or require reassignment (see operator reassignment).

Re-enable

POST /v1/associates/88/activations

200 OK
{
  "id": 88,
  "status": "ACTIVE",
  ...
}

Associate hierarchies

For models where some associates report to others (e.g., a supervisor over drivers), use parentAssociateId:

POST /v1/associates
{
  "type": "DRIVER",
  "name": "Operario",
  "lastName": "100",
  "taxId": "20888888880",
  ...
  "parentAssociateId": 50    // supervisor ID
}

List the subordinates of a supervisor:

GET /v1/associates?parentAssociateId=50

Common errors

Scenario	HTTP	code
Duplicate associate by taxId	200	(upsert, returns existing)
taxId with invalid format	400	validation
Missing required field	400	validation
Operation on a DISABLED associate	422	associate-disabled

No bulk creation for now

Like clients, bulk creation of associates is being evaluated for future versions.