Get a client

curl https://api.example.test/v1/clients/$CLIENT_ID \  -H "Authorization: Bearer $TOKEN"

One client. A client outside the token's team, or one a guest's projects do not name, is 404 RESOURCE_NOT_FOUND.

status runs prospect, active, dormant and churned; it is set by hand and says where the relationship stands, not whether the client is archived, which archived_at says.
notes is HTML filtered to a safe subset; country is a two-letter code and timezone an identifier such as Asia/Colombo.

Requires ability

client:view

The token must hold this ability, or the call is refused with 403.

MCP tool

get_client

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted in the app under Account Settings, then API Tokens, sent as Authorization: Bearer zg_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team, and optionally to one project, at mint time.

In: header

Path Parameters

client*string

The client, resolved by the route binder.

Formatuuid

Responses

200OKapplication/json

The client.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (a zg_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who registered a row answers FORBIDDEN with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/clients/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "c1a2b3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "name": "Acme Retail",    "legal_name": "Acme Retail (Pvt) Ltd",    "website": "https://acme.example",    "industry": "Retail",    "country": "LK",    "timezone": "Asia/Colombo",    "primary_contact_name": "Jane Perera",    "primary_contact_email": "jane@acme.example",    "notes": "<p>Prefers a weekly status call on Tuesdays.</p>",    "status": "active",    "archived_at": null,    "created_at": "2026-08-20T10:05:00+00:00",    "updated_at": "2026-10-24T16:40:00+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: ClientResource;}export interface ClientResource {  id: string;  team_id: string;  name: string;  legal_name: string | null;  website: string | null;  industry: string | null;  country: string | null;  timezone: string | null;  primary_contact_name: string | null;  primary_contact_email: string | null;  notes: string | unknown[] | null;  status: string;  projects_count?: number;  archived_at: string | null;  created_at: string | null;  updated_at: string | null;}

Get a client

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Authorization

Path Parameters

Responses