Plans & entitlements

Access is granted on two axes: per-endpoint (hard 403 if your plan rank is below the gate) and per-field (silently suppressed in the response).

Plans

The exact, current rules — including any country-specific overrides — live in /v3/whoami. Each rule carries the row's min_plan code and a derived accessible boolean computed against your plan rank.

Endpoint enforcement

Endpoints whose gate is above your plan return:

HTTP/1.1 403 Forbidden
X-Required-Plan: pro
Content-Type: application/problem+json

{
  "type":       "https://api.datocapital.com/problems/plan-insufficient",
  "title":      "Plan upgrade required",
  "status":     403,
  "detail":     "This endpoint requires the 'pro' plan or higher; the caller is on 'starter'.",
  "instance":   "/v3/companies/.../representatives"
}

Field enforcement

Fields above your plan are simply absent from the response — same shape as fields whose underlying data is null. This matches the @JsonInclude(NON_NULL) philosophy of the rest of the surface and avoids leaking rows the caller can't render anyway.

Example (free vs starter on the same UEC):

free:
  registered_address: { city, country }
  (no subscribed_capital, paid_in_capital, latitude, longitude, line1, postal_code)

starter+:
  registered_address: { city, country, line1, postal_code, latitude, longitude }
  subscribed_capital, paid_in_capital visible

Country overrides

Every rule is keyed on (entity, field, country). The virtual country code WW means "default, every country". A country-specific row, when present, overrides the WW default for that one country — so policy can be tighter for offshore jurisdictions without rewriting every entry.

Inspecting your tier

Hit /v3/whoami on any plan and filter the entitlements blob client-side. Rows where accessible: false are exactly what you'd unlock by upgrading.