Clients API — manage customers and addresses

The Clients API lets you create and manage customer accounts and their associated delivery addresses. All write operations require the clientes:write permission; reads require clientes:read. Deleting a client performs a soft delete (sets activo = false) rather than removing the record.

List clients

GET /api/clientes

string

Returns a paginated list of clients, optionally filtered by active status. Eagerly loads the direcciones array on each client. Required permission: clientes:read

Query parameters

skip

integer

default:"0"

Number of records to skip for pagination.

limit

integer

default:"50"

Maximum number of records to return. Hard cap: 200.

activo

boolean

default:"true"

Filter by active status. Pass false to list deactivated clients. Omit to use the default (true).

Response `200`

Array of client objects.

integer

required

Unique client identifier.

nombre

string

required

Full name of the client.

string

required

Email address. Must be unique across all clients.

telefono

string

Contact phone number.

cc_id

string

National ID / document number.

activo

boolean

required

Whether the client account is active.

fecha_registro

string (datetime)

ISO 8601 timestamp of account creation.

direcciones

object[]

List of delivery addresses associated with this client.

Show address fields

integer

required

Unique address identifier.

cliente_id

integer

required

Parent client ID.

direccion

string

required

Street address.

distrito

string

District or neighbourhood.

ciudad

string

City.

estado

string

State or region.

pais

string

Country.

es_principal

boolean

Whether this is the primary address.

curl https://api.rappi2.com/api/clientes?activo=true&limit=20 \
  -H "Authorization: Bearer <token>"

Create a client

POST /api/clientes

string

Creates a new client account. Returns 400 if the email is already registered. Required permission: clientes:write

Request body

nombre

string

required

Full name of the client.

string

required

Valid email address. Must be unique.

telefono

string

Contact phone number.

cc_id

string

National ID / document number.

Response `201`

The newly created client object (same shape as the list response).

curl -X POST https://api.rappi2.com/api/clientes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Ana Torres", "email": "ana@example.com", "telefono": "999000111"}'

Get a client

GET /api/clientes/{cliente_id}

string

Returns a single client including their addresses. Returns 404 if not found. Required permission: clientes:read

Path parameters

cliente_id

integer

required

Client ID.

Response `200`

Client object (same shape as list items).

curl https://api.rappi2.com/api/clientes/42 \
  -H "Authorization: Bearer <token>"

Update a client

PATCH /api/clientes/{cliente_id}

string

Partially updates a client record. Only fields provided in the request body are changed. Required permission: clientes:write

Path parameters

cliente_id

integer

required

Client ID.

Request body

All fields are optional.

nombre

string

New full name.

string

New email address. Must be unique.

telefono

string

New phone number.

cc_id

string

New national ID.

activo

boolean

Manually set the active flag.

Response `200`

Updated client object.

curl -X PATCH https://api.rappi2.com/api/clientes/42 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"telefono": "999000222"}'

Deactivate a client

DELETE /api/clientes/{cliente_id}

string

Soft-deletes the client by setting activo = false. The record is retained in the database. Required permission: clientes:delete

Path parameters

cliente_id

integer

required

Client ID.

Response `204`

No body.

curl -X DELETE https://api.rappi2.com/api/clientes/42 \
  -H "Authorization: Bearer <token>"

Add an address

POST /api/clientes/{cliente_id}/direcciones

string

Adds a delivery address to a client. If es_principal is true, any previously marked principal address is automatically demoted. Required permission: clientes:write

Path parameters

cliente_id

integer

required

Client ID.

Request body

direccion

string

required

Street address.

distrito

string

District or neighbourhood.

ciudad

string

City.

estado

string

State or region.

pais

string

Country.

es_principal

boolean

default:"false"

Mark this address as the client’s primary delivery address.

Response `201`

The created address object.

curl -X POST https://api.rappi2.com/api/clientes/42/direcciones \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"direccion": "Av. Larco 1234", "distrito": "Miraflores", "ciudad": "Lima", "es_principal": true}'

List addresses

GET /api/clientes/{cliente_id}/direcciones

string

Returns all delivery addresses for a client. Required permission: clientes:read

Path parameters

cliente_id

integer

required

Client ID.

Response `200`

Array of address objects.

curl https://api.rappi2.com/api/clientes/42/direcciones \
  -H "Authorization: Bearer <token>"

Update an address

PATCH /api/clientes/{cliente_id}/direcciones/{direccion_id}

string

Partially updates a delivery address. Setting es_principal: true demotes any other principal address for this client. Required permission: clientes:write

Path parameters

cliente_id

integer

required

Client ID.

direccion_id

integer

required

Address ID.

Request body

All fields are optional.

direccion

string

New street address.

distrito

string

New district.

ciudad

string

New city.

estado

string

New state or region.

pais

string

New country.

es_principal

boolean

Promote this address to principal.

Response `200`

Updated address object.

curl -X PATCH https://api.rappi2.com/api/clientes/42/direcciones/7 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"es_principal": true}'

Delete an address

DELETE /api/clientes/{cliente_id}/direcciones/{direccion_id}

string

Permanently removes a delivery address. Required permission: clientes:write

Path parameters

cliente_id

integer

required

Client ID.

direccion_id

integer

required

Address ID.

Response `204`

No body.

curl -X DELETE https://api.rappi2.com/api/clientes/42/direcciones/7 \
  -H "Authorization: Bearer <token>"

Auth & Users

Operations

Logistics

Analytics

Clients API — manage customers and addresses

List clients

Query parameters

Response `200`

Create a client

Request body

Response `201`

Get a client

Path parameters

Response `200`

Update a client

Path parameters

Request body

Response `200`

Deactivate a client

Path parameters

Response `204`

Add an address

Path parameters

Request body

Response `201`

List addresses

Path parameters

Response `200`

Update an address

Path parameters

Request body

Response `200`

Delete an address

Path parameters

Response `204`

Build docs developers (and LLMs) love

Auth & Users

Operations

Logistics

Analytics

Documentation Index

​List clients

​Query parameters

​Response 200

​Create a client

​Request body

​Response 201

​Get a client

​Path parameters

​Response 200

​Update a client

​Path parameters

​Request body

​Response 200

​Deactivate a client

​Path parameters

​Response 204

​Add an address

​Path parameters

​Request body

​Response 201

​List addresses

​Path parameters

​Response 200

​Update an address

​Path parameters

​Request body

​Response 200

​Delete an address

​Path parameters

​Response 204

Build docs developers (and LLMs) love

List clients

Query parameters

Response `200`

Create a client

Request body

Response `201`

Get a client

Path parameters

Response `200`

Update a client

Path parameters

Request body

Response `200`

Deactivate a client

Path parameters

Response `204`

Add an address

Path parameters

Request body

Response `201`

List addresses

Path parameters

Response `200`

Update an address

Path parameters

Request body

Response `200`

Delete an address

Path parameters

Response `204`