Skip to main content
POST
/
api
/
v1
/
clients
/
search-by-document
Search Client by Document
curl --request POST \
  --url https://api.example.com/api/v1/clients/search-by-document \
  --header 'Content-Type: application/json' \
  --data '
{
  "company_id": 123,
  "tipo_documento": "<string>",
  "numero_documento": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "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>"
    }
  },
  "errors": {}
}
Searches for an active client by their document type and number within a specific company. This endpoint is useful for quickly finding client information when issuing invoices or other documents.

​
Authentication

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

​
Request Body

​
company_id
integer
required
ID of the company to search within
​
tipo_documento
string
required
Document type code. 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)
​
numero_documento
string
required
Document number to search for (max 20 characters)

​
Response

​
success
boolean
Indicates if the request was successful
​
message
string
Error message (only present when success is false)
​
data
object
The found client object (only present when success is true)
​
id
integer
Client ID
​
company_id
integer
Associated company ID
​
tipo_documento
string
Document type code
​
numero_documento
string
Document number
​
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 (always true for search results)
​
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
​
errors
object
Validation errors (only present when validation fails)

​
Example Request

cURL
curl -X POST "https://api.example.com/api/v1/clients/search-by-document" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "company_id": 1,
    "tipo_documento": "6",
    "numero_documento": "20123456789"
  }'
JavaScript
const response = await fetch('https://api.example.com/api/v1/clients/search-by-document', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token_here',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    company_id: 1,
    tipo_documento: '6',
    numero_documento: '20123456789'
  })
});

const data = await response.json();
PHP
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.example.com/api/v1/clients/search-by-document');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer your_token_here',
    'Content-Type: application/json',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'company_id' => 1,
    'tipo_documento' => '6',
    'numero_documento' => '20123456789'
]));
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."
    }
  }
}
404 Not Found
{
  "success": false,
  "message": "Cliente no encontrado"
}
422 Validation Error
{
  "success": false,
  "message": "Errores de validación",
  "errors": {
    "company_id": [
      "The company_id field is required."
    ],
    "tipo_documento": [
      "The tipo_documento field is required.",
      "The selected tipo_documento is invalid."
    ],
    "numero_documento": [
      "The numero_documento field is required."
    ]
  }
}
500 Error
{
  "success": false,
  "message": "Error al buscar cliente: Database connection failed"
}
This endpoint only returns active clients. If a client exists but is marked as inactive (activo: false), it will not be returned and you’ll receive a 404 error.
The search is performed using exact matching on all three parameters: company_id, tipo_documento, and numero_documento. All three fields must match exactly for a client to be found.

​
Use Cases

This endpoint is particularly useful when:
  • Creating invoices: Quickly look up client information by their RUC or DNI before generating an invoice
  • Validating documents: Check if a client exists in your system before creating a new one
  • Auto-completing forms: Populate form fields with client data when the user enters a document number
  • Point of sale systems: Retrieve client details during the checkout process

​
Validation Rules

  • company_id: Required, must reference an existing company
  • tipo_documento: Required, must be one of: 1, 4, 6, 7, or 0
  • numero_documento: Required, max 20 characters

Build docs developers (and LLMs) love

Get started for freeTalk to us