ITMS API — PUT /api/v1/provider/clients/{client_id}/filing-obligations/{state}

Record an already-issued customer registration and activate filing for one client state.

PUT/api/v1/provider/clients/{client_id}/filing-obligations/{state}

Record an already-issued customer registration and activate filing for one client state.

Persistence: Writes the registration, obligation timeline, and state account profile in the taxpayer tenant. Never registers the customer with a state.
Auth: Provider API key · scopes provider:clients:write and returns:write
Request: filing_frequency, optional registration_number/date, account_key/name/fields, and forward/back return generation flags
Response: Registration id/status, filing frequency, and generated return counts

Request template for this operation

Set ITMS_API_KEY to a key with the scope shown above. Use a sandbox key while developing. For cURL, set CLIENT_ID_URLENCODED, STATE_URLENCODED; JavaScript and Python URL-encode the corresponding raw environment values. Create request.json from this operation’s OpenAPI request schema for cURL, and set ITMS_REQUEST_BODY to that same JSON for JavaScript or Python. Do not copy production customer data into a sandbox request.

cURL

: "${CLIENT_ID_URLENCODED:?Set CLIENT_ID_URLENCODED to the URL-encoded client_id}"
: "${STATE_URLENCODED:?Set STATE_URLENCODED to the URL-encoded state}"
curl --request PUT \
  --url "${ITMS_BASE_URL:-https://prophit.ai}/api/v1/provider/clients/${CLIENT_ID_URLENCODED}/filing-obligations/${STATE_URLENCODED}" \
  --header "Authorization: Bearer ${ITMS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

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 requestBody = JSON.parse(requiredEnv("ITMS_REQUEST_BODY"));
const path = `/api/v1/provider/clients/${encodeURIComponent(requiredEnv("CLIENT_ID"))}/filing-obligations/${encodeURIComponent(requiredEnv("STATE"))}`;
const response = await fetch(`${process.env.ITMS_BASE_URL ?? 'https://prophit.ai'}${path}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${requiredEnv('ITMS_API_KEY')}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(requestBody),
});
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 json
from urllib.parse import quote
import requests

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

request_body = json.loads(required_env("ITMS_REQUEST_BODY"))
path = f"/api/v1/provider/clients/{quote(required_env('CLIENT_ID'), safe='')}/filing-obligations/{quote(required_env('STATE'), safe='')}"
response = requests.request(
    "PUT",
    f"{os.getenv('ITMS_BASE_URL', 'https://prophit.ai')}{path}",
    headers={
        "Authorization": f"Bearer {required_env('ITMS_API_KEY')}",
    },
    json=request_body,
    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: filing_frequency, optional registration_number/date, account_key/name/fields, and forward/back return generation flags
Response: Registration id/status, filing frequency, and generated return counts

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.

PUT /api/v1/provider/clients/{client_id}/filing-obligations/{state}