Skip to main content

​
Choose the surface

The API provides the public integration contract for the client and external systems. Use the interactive API reference and OpenAPI specification for your target environment and version. Prefer the v3 surface for new integrations; do not infer request fields or response shapes from screenshots or a different release.

​
Agree on configuration first

Before implementation, record the target environment, integration identity, allowed operations, document types, keyword types and groups, and Caseflow application/class where relevant. Names and numeric IDs can differ between environments. Check metadata requirements with the people maintaining Document types and keywords. File format, required fields, repeatable groups, and document access rights are part of a working integration, not just an API developer’s concern.

​
Verify more than a successful request

Use a test environment to check:
  1. The dedicated identity authenticates and reaches only the intended records.
  2. Required and optional metadata arrive in the expected types and groups.
  3. The returned response is handled according to the selected API contract, including empty results and validation failures.
  4. An accepted asynchronous operation reaches its intended final state, with a trace or correlation identifier retained for investigation.
  5. A retry after an uncertain response does not accidentally create duplicate business work. Do not assume every operation is safe to repeat.
For sensitive content, a not-found response can also mean the caller cannot access the object. For administrative resources, forbidden generally indicates a missing permission. Check identity and access before concluding that the environment has lost a record.

​
Don’t overwrite a colleague’s configuration change

An integration or script that changes configuration through the API — a banner, a keyword type, a user, a retention policy — should send back the version it read. Configuration reads return a version for each item. Items read from a list carry a version field; send it back with the update. Settings read as a single object, such as the general and upload settings, return the version in the ETag header; send it back in If-Match. Deletes, and some replace operations, also take it in If-Match. If someone changed the item after you read it, the request is refused with 409 Conflict and nothing is written: read the item again and decide whether your change still applies. This holds in every configuration area, including users, user groups, group rights, permission grants and feature access. The version is optional. A write without one applies to the item as it is now, so the last write wins. The admin pages, the admin assistant and AI assistant access always send it. Creating an item needs no version. The admin assistant’s own environment settings are the exception: a write to them without the version is refused. In If-Match, a weak tag (W/"…") counts the same as the tag without W/. No header, an empty tag and * all count as no version sent: a write that takes an optional version applies to the item as it is now, and a write that requires one is refused as missing its version. Where a configuration endpoint takes the version, and under which field or header, is in the API reference for your target environment and version.

​
Read a refused configuration change

Every configuration area refuses a write in the same format: a standard problem response with an errors array, one entry per problem.
field is the path of the value in your request, and code says what is wrong with it, such as required, notFound, duplicate, notAllowed or stale. Act on field and code: message is English text for logs, and detail joins the messages for tools that read only the standard problem fields. A body that cannot be read at all — an array where an object is expected, for example — gets the framework’s own 400 validation response instead. Removing a member from a keyword type group or an autofill set, and deleting an autofill set, can be sent again with confirmDataLoss=true when the only thing blocking them is the stored values they would delete. Deleting a keyword type group cannot: it is refused for as long as its members hold values.

​
Adapt an integration built on an earlier release

The release that introduced the admin assistant moved configuration writes onto one write path, shared by the admin pages, the API, the admin assistant and AI assistant access. An integration or script written against an earlier release has to adapt to these changes:
  • The error format. Refusals use the errors array above instead of each area’s own shape. A client that expects errors to be an object keyed by field name cannot read it.
  • Versions. Updates and deletes in every configuration area check the version you send, as described above; before, most areas had none and the last write won. Handle 409 Conflict by reading the item again.
  • Five requests changed shape. The old shape is refused with 400:
  • Removed endpoints. The editor AI endpoints are gone; the admin assistant and AI assistant access replace them, and propose their changes for approval instead:
    • GET and PUT /api/v3/ai/policy
    • POST /api/v3/ai/caseflow-templates/generate and POST /api/v3/ai/form-templates/generate
    • POST /api/v3/ai/scripts/author/stream and POST /api/v3/ai/workflow/author/stream

​
Support handover

Keep the integration owner, purpose, API client ID, granted group, environment, credential-rotation process, and recovery procedure with the integration’s operational record. For failures, collect time, operation, response status, and correlation/trace ID when available. Do not copy bearer tokens or secrets into tickets.

Pending uploads queue

Let a scanner or another system queue files that people index and archive in the upload tool.

Configure a Microsoft 365 mailbox

Connect a mailbox, choose how mail and attachments are archived, and start postprocessing workflows.