Skip to main content
GET
/
api
/
v1
/
clients
List Clients
curl --request GET \
  --url https://api.example.com/api/v1/clients
{
  "success": true,
  "data": [
    {
      "id": 123,
      "company_id": 123,
      "tipo_documento": "<string>",
      "numero_documento": "<string>",
      "razon_social": "<string>",
      "nombre_comercial": "<string>",
      "direccion": "<string>",
      "ubigeo": "<string>",
      "distrito": "<string>",
      "provincia": "<string>",
      "departamento": "<string>",
      "telefono": "<string>",
      "email": "<string>",
      "activo": true,
      "created_at": "<string>",
      "updated_at": "<string>",
      "company": {
        "id": 123,
        "ruc": "<string>",
        "razon_social": "<string>"
      }
    }
  ],
  "meta": {
    "total": 123,
    "per_page": 123,
    "current_page": 123,
    "last_page": 123
  }
}
Retrieves a paginated list of clients with optional filtering by company, document type, and text search.

​
Authentication

This endpoint requires authentication using a Bearer token. 
Authorization: Bearer {your_token}

​
Query Parameters

​
company_id
integer
Filter clients by company ID
​
tipo_documento
string
Filter by document type. Valid values:
  • 1 - DNI (National ID)
  • 4 - Carnet de Extranjería (Foreign ID)
  • 6 - RUC (Tax ID)
  • 7 - Passport
  • 0 - DOC.TRIB.NO.DOM.SIN.RUC (Foreign Tax Document)
​
search
string
Search text to filter by document number, legal name (razon_social), or commercial name (nombre_comercial)
​
page
integer
default:"1"
Page number for pagination

​
Response

​
success
boolean
Indicates if the request was successful
​
data
array
Array of client objects
​
id
integer
Client ID
​
company_id
integer
Associated company ID
​
tipo_documento
string
Document type code (1, 4, 6, 7, 0)
​
numero_documento
string
Document number (RUC, DNI, etc.)
​
razon_social
string
Legal name of the client
​
nombre_comercial
string
Commercial name
​
direccion
string
Physical address
​
ubigeo
string
6-digit UBIGEO code
​
distrito
string
District name
​
provincia
string
Province name
​
departamento
string
Department name
​
telefono
string
Phone number
​
email
string
Email address
​
activo
boolean
Whether the client is active
​
created_at
string
Timestamp when the client was created
​
updated_at
string
Timestamp when the client was last updated
​
company
object
Associated company information
​
id
integer
Company ID
​
ruc
string
Company RUC
​
razon_social
string
Company legal name
​
meta
object
Pagination metadata
​
total
integer
Total number of clients
​
per_page
integer
Number of items per page (default: 20)
​
current_page
integer
Current page number
​
last_page
integer
Last page number

​
Example Request

cURL
curl -X GET "https://api.example.com/api/v1/clients?company_id=1&tipo_documento=6&search=20123456789" \
  -H "Authorization: Bearer your_token_here" \
  -H "Accept: application/json"
JavaScript
const response = await fetch('https://api.example.com/api/v1/clients?company_id=1&tipo_documento=6', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_token_here',
    'Accept': 'application/json'
  }
});

const data = await response.json();
PHP
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.example.com/api/v1/clients?company_id=1');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer your_token_here',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

​
Example Response

200 Success
{
  "success": true,
  "data": [
    {
      "id": 1,
      "company_id": 1,
      "tipo_documento": "6",
      "numero_documento": "20123456789",
      "razon_social": "EMPRESA DEMO S.A.C.",
      "nombre_comercial": "Empresa Demo",
      "direccion": "Av. Los Comerciantes 123",
      "ubigeo": "150101",
      "distrito": "Lima",
      "provincia": "Lima",
      "departamento": "Lima",
      "telefono": "01-2345678",
      "email": "[email protected]",
      "activo": true,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "company": {
        "id": 1,
        "ruc": "20987654321",
        "razon_social": "MI EMPRESA S.A.C."
      }
    },
    {
      "id": 2,
      "company_id": 1,
      "tipo_documento": "1",
      "numero_documento": "12345678",
      "razon_social": "Juan Pérez García",
      "nombre_comercial": null,
      "direccion": "Jr. Las Flores 456",
      "ubigeo": "150102",
      "distrito": "Ancón",
      "provincia": "Lima",
      "departamento": "Lima",
      "telefono": "987654321",
      "email": "[email protected]",
      "activo": true,
      "created_at": "2024-01-16T14:20:00.000000Z",
      "updated_at": "2024-01-16T14:20:00.000000Z",
      "company": {
        "id": 1,
        "ruc": "20987654321",
        "razon_social": "MI EMPRESA S.A.C."
      }
    }
  ],
  "meta": {
    "total": 2,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}
500 Error
{
  "success": false,
  "message": "Error al obtener clientes: Database connection failed"
}
The endpoint returns 20 clients per page by default. Use the page query parameter to navigate through multiple pages.
Clients are returned with their associated company information using eager loading for optimal performance. The search parameter performs a case-insensitive partial match on document number, legal name, and commercial name.

Build docs developers (and LLMs) love

Get started for freeTalk to us