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": "cus_8f7b2c..."
  }
}

Automated Business Rules

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

• Payment terms (terminos) must be valid (contado, net30, net60). 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": "cus_8f7b2c...",
      "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": "",
      "createdAt": "2026-08-01T10:00:00.000Z",
      "nCotizaciones": 4,
      "cerrado": 32000
    }
  ],
  "meta": { "limit": 100, "offset": 0, "total": 1 }
}

direccionLine1/direccionLine2, ciudad, and region come back on reads (the app fills them in to satisfy the recipient’s address on an invoice), but the API doesn’t accept them yet — today they’re only captured from Settings › Clients. country_code is accepted on create and update.

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, and country_code. 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/8f7b2c..." \
     -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.