Skip to content
ESEN

Clients

Synchronize your database of organizations and commercial prospects.

Overview

The Client object contains the master commercial record of the people or organizations you bill. Synchronizing clients via the API is the foundation for keeping Cord perfectly aligned with your ERP or CRM (like Salesforce or HubSpot).

Creating a Client

Create a new client by sending a POST /api/v1/clientes. The only strictly required field is the company name (empresa); everything else is optional and depends on your business and country. rfc is the Mexican tax ID (Registro Federal de Contribuyentes) — it only applies if your client is invoiced in Mexico. If your business or your client is in another country, just omit the field; Cord doesn’t require an rfc to create or invoice a client outside Mexico.

Request:

curl -X POST "https://cordhq.app/api/v1/clientes" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{
       "empresa": "Stark Industries",
       "contacto": "Tony Stark",
       "email": "tony@stark.com",
       "rfc": "STA120412XYZ",
       "terminos": "net30",
       "limite": 500000,
       "nivel": "oro",
       "descuento_pct": 15
     }'

Successful Response:

{
  "data": {
    "id": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b"
  }
}

Automated Business Rules

When you create clients via API, Cord applies real-time logical constraints:

  • Payment terms (terminos) must be valid: contado or net7, net15, net30, net45, net60, net90 (N days of credit). If you pass an invalid term, it defaults to contado.
  • Partnership level (nivel) is restricted to estandar, plata, oro, or distribuidor.
  • The RFC (if you send one) is normalized to uppercase automatically.
  • The discount (descuento_pct) is mathematically bounded between 0 and 100.

Listing Clients

Retrieve the complete catalog using Pagination.

curl -X GET "https://cordhq.app/api/v1/clientes?limit=100" \
     -H "Authorization: Bearer sk_live_tU..."
{
  "data": [
    {
      "id": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b",
      "empresa": "Stark Industries",
      "contacto": "Tony Stark",
      "email": "tony@stark.com",
      "telefono": "",
      "rfc": "STA120412XYZ",
      "terminos": "Net 30",
      "terminosCode": "net30",
      "limite": 500000,
      "nivel": "oro",
      "descuentoPct": 15,
      "countryCode": "",
      "direccionLine1": "",
      "ciudad": "",
      "region": "",
      "language": "en",
      "createdAt": "2026-08-01T10:00:00.000Z",
      "nCotizaciones": 4,
      "cerrado": 32000
    }
  ],
  "meta": { "limit": 100, "offset": 0, "total": 1, "next_cursor": null }
}

When creating a client, POST /api/v1/clientes also accepts the recipient’s address and tax details: country_code (ISO 3166-1 alpha-2), direccion_line1 and direccion_line2 (up to 200 characters), ciudad and region (up to 100), and for Mexico regimen_fiscal, uso_cfdi, and cp_fiscal. On reads they come back as countryCode, direccionLine1, direccionLine2, ciudad, region, regimenFiscal, usoCfdi, and cpFiscal. When updating with PATCH, only country_code from that group can be changed; the address and tax details are edited from the client’s record in the app.

When creating you can also send buyer_reference: the buyer reference their European e-invoices carry by default (in Germany, a public body’s Leitweg-ID). An invoice can carry its own; see the Invoices API.

Validated tax ID

Cord validates rfc with the check digits of the client’s country or, if you don’t send country_code, your account’s country: RFC in Mexico, NIF/NIE/CIF in Spain, EIN in the United States, CNPJ or CPF in Brazil, NIT in Colombia, CUIT in Argentina, RUT in Chile, RUC in Peru, SIREN, SIRET, or TVA in France, USt-IdNr. or Steuernummer in Germany, VAT or UTR in the United Kingdom, and Business Number in Canada. One that fails responds 422 with code: "invalid_tax_id" and a reason that names the local ID. When updating, it’s only validated if you change the ID or the country: an old value doesn’t block you from fixing the phone or the email.

Document language

language is the language in which the client receives their quotes, invoices, PDFs, emails, and links: es, en, pt, fr, or de; null means your organization’s. Send it when creating and when updating. In PATCH, omitting it keeps it, and sending null or an empty string goes back to your organization’s. Any other value returns 400 with code: "invalid_request" and field: "language". Changing it doesn’t rewrite what was already sent: each quote and invoice keeps the language it was sent or issued in.

Searching clients

q searches company, contact, email, and RFC. email matches the exact email, case-insensitive; use it to avoid duplicates before creating a client from another tool.

curl -X GET "https://cordhq.app/api/v1/clientes?email=tony@stark.com" \
     -H "Authorization: Bearer sk_live_tU..."

Retrieving a Client

GET /api/v1/clientes/{id} returns the same object as the list. An id from another organization returns 404.

Updating a Client

PATCH /api/v1/clientes/{id} changes only the fields you send: empresa, contacto, email, telefono, rfc, terminos, country_code, and language. Everything else is kept. Credit limit, level, and discount can’t be changed through this endpoint even if you send them. Requires a key with write permission.

curl -X PATCH "https://cordhq.app/api/v1/clientes/8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{ "email": "procurement@stark.com" }'
{ "data": { "ok": true } }

Every change emits the client.updated event.