Clients — Create & Update

Create new clients and update existing ones with partial updates.

---

Create Client

POST/apidev/v1/clients

PermissionAPICLI_CLIENTS_WRITE

Rate Limit10 req/min

Upsert by external_code

Clients are unique by external_code within your company. If a client with the same external_code already exists, this request does not create a duplicate: it returns that existing client, with created: false in the response.

On a match, only name and zip_code are refreshed with the values you sent. Every other field of the existing client is left untouched — to change the rest, follow up with Update Client using the id you got back.

When you omit external_code, the client's name (uppercased) is used as its external code — so re-posting the same name also matches the existing client.

Request Body

Field	Type	Required	Max	Description
name	string	Yes	200	Client display name.
external_code	string	No	120	External system identifier.
status	string	No	10	Client status.
document	string	No	60	Document number.
document_type	number	No	—	Document type identifier.
business_name	string	No	200	Legal business name.
tax_id	string	No	60	Tax identification number.
phone	string	No	60	Phone number.
mobile	string	No	60	Mobile phone.
email	string	No	200	Email address.
notes	string	No	1000	Free-text notes.
image_url	string	No	500	Image URL.
street	string	No	200	Street name.
door_number	string	No	20	Door number.
apartment	string	No	20	Apartment or suite.
corner	string	No	200	Cross street.
zip_code	string	No	20	Postal code.
latitude	number	No	—	Latitude coordinate.
longitude	number	No	—	Longitude coordinate.
country_id	string	No	30	Country ID.
department_id	string	No	30	Department ID.

Code Examples

cURL

curl -s -X POST "https://$TENANT/apidev/v1/clients" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Regional Distributors",
    "business_name": "Regional Distributors S.A.",
    "tax_id": "219900005018",
    "email": "info@regionaldist.com",
    "phone": "+59821009876",
    "street": "Bvar. Artigas",
    "door_number": "567",
    "country_id": "1",
    "department_id": "10"
  }'

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/clients`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Regional Distributors',
      business_name: 'Regional Distributors S.A.',
      tax_id: '219900005018',
      email: 'info@regionaldist.com',
      phone: '+59821009876',
      street: 'Bvar. Artigas',
      door_number: '567',
      country_id: '1',
      department_id: '10',
    }),
  }
);
const { data } = await res.json();
console.log(`Created client: ${data.id}`);

Python

import requests

response = requests.post(
    f"https://{TENANT}/apidev/v1/clients",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    json={
        "name": "Regional Distributors",
        "business_name": "Regional Distributors S.A.",
        "tax_id": "219900005018",
        "email": "info@regionaldist.com",
        "phone": "+59821009876",
        "street": "Bvar. Artigas",
        "door_number": "567",
        "country_id": "1",
        "department_id": "10",
    },
)
result = response.json()
print(f"Created client: {result['data']['id']}")

Response Fields

Field	Type	Description
id	string	Client unique identifier — the new client's id, or the existing client's id when the request matched one by external_code.
created	boolean	true when a new client was created; false when an existing client with the same external_code was updated instead.

Example Response

{
  "success": true,
  "data": {
    "id": "982710394857200005",
    "created": true
  }
}

---

Update Client

Update an existing client. Only included fields are modified; omitted fields remain unchanged. Send null to clear a nullable field.

See Partial Updates for the general pattern.

PUT/apidev/v1/clients/{id}

PermissionAPICLI_CLIENTS_WRITE

Rate Limit10 req/min

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Client unique identifier.

Request Body

All fields from Create Client are accepted (none required). Only include the fields you want to modify.

Code Examples

cURL

curl -s -X PUT "https://$TENANT/apidev/v1/clients/982710394857200005" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-info@regionaldist.com",
    "phone": "+59821005555",
    "notes": "Updated primary contact"
  }'

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/clients/982710394857200005`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'new-info@regionaldist.com',
      phone: '+59821005555',
      notes: 'Updated primary contact',
    }),
  }
);
const { data } = await res.json();
console.log(`Updated fields: ${data.updated_fields.join(', ')}`);

Python

import requests

response = requests.put(
    f"https://{TENANT}/apidev/v1/clients/982710394857200005",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    json={
        "email": "new-info@regionaldist.com",
        "phone": "+59821005555",
        "notes": "Updated primary contact",
    },
)
result = response.json()
print(f"Updated: {result['data']['updated_fields']}")

Example Response

{
  "success": true,
  "data": {
    "id": "982710394857200005",
    "updated_fields": ["email", "phone", "notes"]
  },
  "meta": {}
}

---

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid parameters.
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	User lacks required permission.
NOT_FOUND	404	Resource not found (update endpoint).
RATE_LIMITED	429	Exceeded 10 req/min.
INTERNAL_ERROR	500	Unexpected server error.

---

Related

• Authentication
• List & Detail Clients
• Accounts API
• Partial Updates
• Rate Limits
• Error Handling