Clients
Find a client by external ID
Look up a client by their `external_id` (sent in the JSON body), the integration key that maps them to a record in a third-party system (ERP/CRM/e-commerce). Distinct from the fiscal `tax_id`. Returns the matching client or 404 if no client uses that external_id within your company.
AuthorizationBearer <token>
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
import { Factuarea } from "@factuarea/sdk";const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });const result = await factuarea.clients.findByExternalId({ // request body — see the schema below });{
"data": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
"object": "client",
"name": "Acme Corporation",
"commercial_name": "Acme SL",
"tax_id": "B12345678",
"vat_id": "ESB12345678",
"email": "billing@acme.com",
"phone": "+34 600 123 456",
"fax": "+34 91 123 45 68",
"mobile": "+34 600 000 000",
"website": "https://acme.com",
"contact_person": "Juan García",
"billing_emails": [
"facturacion@acme.com",
"contabilidad@acme.com"
],
"address": {
"line1": "Calle Mayor 1",
"line2": "Edificio Central",
"number": "42",
"floor": "3",
"door": "B",
"staircase": "A",
"postal_code": "28001",
"city": "Madrid",
"province": "Madrid",
"country": "ES"
},
"coordinates": {
"latitude": 39.4699,
"longitude": -0.3763
},
"default_discount": 5,
"default_vat_rate": 21,
"default_retention_rate": 15,
"is_surcharge_subject": false,
"bank_accounts": [
{
"object": "bank_account",
"iban": "ES7621000418401234567891",
"bic": "CAIXESBBXXX",
"is_default": true
}
],
"preferred_operation_regime": "general",
"accumulate_347": true,
"alternative_id": {
"object": "alternative_id",
"type": "tax_id_foreign",
"value": "EU123456789",
"country_code": "FR"
},
"payment_preferences": {
"object": "payment_preferences",
"method": "bank_transfer",
"terms_days": 30
},
"dir3_accounting_office": "L01280796",
"dir3_managing_body": "L01280796",
"dir3_processing_unit": "L01280796",
"external_id": "CRM-99",
"notes": "Pago al contado.",
"metadata": {
"erp_code": "IVA-GEN",
"ledger_account": "477000"
},
"is_active": true,
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
}{
"error": {
"type": "authentication_error",
"code": "missing_api_key",
"message": "No se ha proporcionado una API key válida en el header Authorization.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
"request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
}
}{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "Esta API key no tiene el scope requerido para esta operación.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
"request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
}
}{
"error": {
"type": "idempotency_error",
"code": "idempotency_key_reused",
"message": "La cabecera `Idempotency-Key` ya se usó con un body distinto. Usa una clave nueva o reenvía exactamente el mismo body.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
"request_id": "req_01HKQS5NHT9A4U7R2E3F8GZWTJ"
}
}{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "El campo `name` es obligatorio y no puede estar vacío.",
"param": "name",
"doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
"request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
}
}{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
"request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
}
}{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
"request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
}
}