Accounts — List & Detail

Query customer accounts with filtering, and retrieve full account profiles with products and dynamic fields.

---

List Accounts

GET/apidev/v1/accounts

PermissionAPICLI_ACCOUNTS_READ

Rate Limit10 req/min

Cache60s

Query Parameters

Parameter	Type	Required	Default	Description
status	string	No	—	Filter by status. Max length 10.
search	string	No	—	Free text search. Max length 120.
client_id	string	No	—	Filter by client ID. Max length 30.
provider_id	string	No	—	Filter by provider ID. Max length 30.
country_id	string	No	—	Filter by country ID. Max length 30.
department_id	string	No	—	Filter by department ID. Max length 30.
city_id	string	No	—	Filter by city ID. Max length 30.
limit	integer	No	25	Number of records per page (1–100). A value outside that range returns 400 VALIDATION_ERROR — it is not clamped silently.
offset	integer	No	0	Number of records to skip for pagination.

Response Fields

Field	Type	Description
id	string	Account identifier.
external_code	string | null	External system code.
name	string | null	Account name.
business_name	string | null	Legal business name.
tax_id	string | null	Tax identification number.
document	string | null	Document number.
phone	string | null	Phone number.
mobile	string | null	Mobile phone.
email	string | null	Email address.
image_url	string | null	Image URL.
status	string | null	Account status.
service_time_min	number | null	Default on-site service time for this account, in minutes (used by the planner).
address	object	Nested: street, door_number, apartment, corner, zip_code, latitude, longitude. latitude / longitude are raw decimal strings (or null) — never JSON numbers, so no precision is lost.
notes	string | null	Free-text notes.
start_date	string | null	Start date, YYYY-MM-DD.
end_date	string | null	End date, YYYY-MM-DD.
birth_date	string | null	Birth date, YYYY-MM-DD. Accounts with no date on file return null (legacy 0001-01-01 placeholders are normalized).
client_name	string | null	Associated client name.
country_name	string | null	Country name.
department_name	string | null	Department name.
city_name	string | null	City name.

Code Examples

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/accounts?status=A&search=acme&limit=10"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/accounts?status=A&search=acme&limit=10`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
    },
  }
);
const { data, meta } = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/accounts",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    params={"status": "A", "search": "acme", "limit": 10},
)
data = response.json()

Example Response

{
  "success": true,
  "data": [
    {
      "id": "982710394857201664",
      "external_code": "EXT-001",
      "name": "Acme Corp",
      "business_name": "Acme Corporation S.A.",
      "tax_id": "214100001019",
      "document": null,
      "phone": "+59821234567",
      "mobile": "+59899123456",
      "email": "contact@acme.com",
      "image_url": null,
      "status": "A",
      "service_time_min": 15,
      "address": {
        "street": "Av. Rivera",
        "door_number": "1234",
        "apartment": "Of. 301",
        "corner": "Soca",
        "zip_code": "11300",
        "latitude": "-34.9011",
        "longitude": "-56.1645"
      },
      "notes": "Premium customer",
      "start_date": "2024-01-15",
      "end_date": null,
      "birth_date": null,
      "client_name": "Regional Distributors",
      "country_name": "Uruguay",
      "department_name": "Montevideo",
      "city_name": "Montevideo"
    }
  ],
  "meta": {
    "total": 87,
    "limit": 10,
    "offset": 0
  }
}

---

Account Detail

GET/apidev/v1/accounts/{id}

PermissionAPICLI_ACCOUNTS_READ

Rate Limit10 req/min

Cache30s

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Account unique identifier.

Additional Response Fields

Returns all fields from the List endpoint, plus:

Field	Type	Description
client_id	string | null	Associated client ID.
country_id	string | null	Country ID.
department_id	string | null	Department ID.
city_id	string | null	City ID.
products	array	Products associated with the account.
dynamic_fields	array	Custom dynamic fields configured for the tenant.

Code Examples

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/accounts/982710394857201664"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/accounts/982710394857201664`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
    },
  }
);
const { data } = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/accounts/982710394857201664",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
)
data = response.json()

Example Response

{
  "success": true,
  "data": {
    "id": "982710394857201664",
    "external_code": "EXT-001",
    "name": "Acme Corp",
    "business_name": "Acme Corporation S.A.",
    "tax_id": "214100001019",
    "document": null,
    "phone": "+59821234567",
    "mobile": "+59899123456",
    "email": "contact@acme.com",
    "image_url": null,
    "status": "A",
    "service_time_min": 15,
    "address": {
      "street": "Av. Rivera",
      "door_number": "1234",
      "apartment": "Of. 301",
      "corner": "Soca",
      "zip_code": "11300",
      "latitude": "-34.9011",
      "longitude": "-56.1645"
    },
    "notes": "Premium customer",
    "start_date": "2024-01-15",
    "end_date": null,
    "birth_date": null,
    "client_id": "982710394857200005",
    "client_name": "Regional Distributors",
    "country_id": "1",
    "country_name": "Uruguay",
    "department_id": "10",
    "department_name": "Montevideo",
    "city_id": "100",
    "city_name": "Montevideo",
    "products": [
      {
        "id": "982710394857201700",
        "provider_id": "982710394857200030",
        "provider_name": "National Insurance Co.",
        "product_type_id": "8",
        "product_type_name": "Vehicle Insurance",
        "coverage_id": "12",
        "coverage_name": "Full Coverage",
        "start_date": "2025-01-01",
        "end_date": "2026-12-31",
        "status": "A"
      }
    ],
    "dynamic_fields": [
      {
        "field_id": "10",
        "name": "Customer Tier",
        "type": "lista",
        "order": 1,
        "value": "Premium"
      },
      {
        "field_id": "11",
        "name": "Contract Signed",
        "type": "boolean",
        "order": 2,
        "value": true
      }
    ]
  },
  "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 (detail endpoint).
RATE_LIMITED	429	Exceeded 10 req/min.
INTERNAL_ERROR	500	Unexpected server error.

---

Related

• Authentication
• Create & Update Accounts
• Clients API
• Pagination
• Rate Limits
• Error Handling