ITMS API — GET /api/v1/provider/clients

List taxpayer engagements owned by the authenticated service provider.

GET/api/v1/provider/clients

List taxpayer engagements owned by the authenticated service provider.

Persistence: Read-only. Prefer client_context_ref in X-ITMS-Client-Ref; client_context_id remains available for X-ITMS-Client-Id.
Auth: Provider API key · scope provider:clients:read
Request: Query params: optional status; limit (1–500); offset
Response: Explicit external and numeric client-context values, canonical organization identity, status, and total

Request template for this operation

Set ITMS_API_KEY to a key with the scope shown above. Use a sandbox key while developing. Do not copy production customer data into a sandbox request.

cURL

curl --request GET \
  --url "${ITMS_BASE_URL:-https://prophit.ai}/api/v1/provider/clients" \
  --header "Authorization: Bearer ${ITMS_API_KEY}"

JavaScript (Node 18+)

const requiredEnv = (name) => {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before running this request.`);
  return value;
};
const path = `/api/v1/provider/clients`;
const response = await fetch(`${process.env.ITMS_BASE_URL ?? 'https://prophit.ai'}${path}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${requiredEnv('ITMS_API_KEY')}`,
  },
});
const requestId = response.headers.get('x-request-id');
const payload = response.status === 204 ? null : await response.json();
if (!response.ok) throw Object.assign(new Error(payload?.error?.message), { code: payload?.error?.code, requestId });
console.log({ requestId, payload });

Python

import os
import requests

def required_env(name):
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Set {name} before running this request.")
    return value

path = f"/api/v1/provider/clients"
response = requests.request(
    "GET",
    f"{os.getenv('ITMS_BASE_URL', 'https://prophit.ai')}{path}",
    headers={
        "Authorization": f"Bearer {required_env('ITMS_API_KEY')}",
    },
    timeout=30,
)
request_id = response.headers.get("x-request-id")
if not response.ok:
    error = response.json().get("error", {})
    raise RuntimeError(f"{error.get('code')}: {error.get('message')} (request_id={request_id})")
print(None if response.status_code == 204 else response.json())

Request and response shape

Request: Query params: optional status; limit (1–500); offset
Response: Explicit external and numeric client-context values, canonical organization identity, status, and total

The versioned OpenAPI document is the machine-readable authority for required fields, types, enums, response schemas, and status codes. This page supplies the product and workflow context around that contract.

Integration contract

Use a key whose environment, organization, location, and scopes match the operation.
Validate the request against the customer OpenAPI document; never infer omitted required facts.
For create, apply, commit, refund, adjustment, or replay operations, follow the documented idempotency and duplicate semantics.
Persist the response request ID, result authority, warnings, and evidence references needed to reproduce the decision.
Handle the machine-readable error envelope and honor rate-limit retry headers.

GET /api/v1/provider/clients