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