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

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']}")

Example Response

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

---

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
BAD_REQUEST	400	Missing required headers.
VALIDATION_ERROR	400	Invalid parameters.
UNAUTHORIZED	401	Invalid or expired JWT / 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