TriStar v2 — Endpoint Usage Review (Response)

Response to the Clio integration team's endpoint mapping review. This document confirms correct v2 routes, clarifies open questions, and notes a few recommendations beyond the mapped calls.

Quick confirmation summary

1. Creating orders

All create flows support export: true to save and export in one call, returning:

{
  "webOrderId": "W123456",
  "workOrderId": "C123456",
  "generatedWorkOrders": [
    {
      "workOrder": "C123456",
      "servee": null
    }
  ]
}

See the Order Lifecycle guide for how draft web order ids relate to exported work order ids.

Job type codes are tenant-specific

Job type codes (for example 77, 99, 184, 236) are not hardcoded in the API. They come from the tenant MessengerJobType table and are filtered by order category. Always call the matching GetJobTypes endpoint for the controller you plan to use and match by title:

Q1 — Are these the correct create endpoints for Court Filing, Process Serve, and Mail Service?

Court Filing — yes.

• Endpoint: POST CourtOrder/Create with export: true
• Job type: jobTypeCode from GET CourtOrder/GetJobTypes (your codes 184 / 183 are valid if returned by that lookup)
• Docs: CourtOrder.Create

Process Serve — yes.

• Endpoint: POST ProcessOrder/Create with export: true
• Job type: jobTypeCode from GET ProcessOrder/GetJobTypes (for example 41)
• Docs: ProcessOrder.Create

Mail Service — yes, with one verification step.

Using POST ProcessOrder/Create with job type 236 ("036 - MAIL SERVICES") is correct if that code appears in GET ProcessOrder/GetJobTypes.

Some tenants classify mail/messenger work under the DELIVERY category instead. If 236 appears in GET DeliveryOrder/GetJobTypes rather than ProcessOrder/GetJobTypes, use:

• Endpoint: POST DeliveryOrder/Create with export: true
• Job type field: orderType (not jobTypeCode)
• Docs: DeliveryOrder.Create

Recommendation: Call both GetJobTypes endpoints once during integration setup and cache which controller owns "036 - MAIL SERVICES" for your tenant. Do not assume 236 is always Process.

2. Tracking orders and documents

Q2 — Are these the correct endpoints for tracking? Anything to do differently?

Your mapping is correct. A few practices will make polling more reliable:

Use ProcessStatus/Search as the primary poll

POST ProcessStatus/Search is the right recurring poll for all order types, including legacy v1 orders. It uses the same Status Online search as Tristar.Web and accepts file number, work order, case number, parties, and other keyword fields.

Each result includes a type field that tells you which GetExisting endpoint to call:

Docs: ProcessStatus.Search

Compatibility aliases (optional)

If you prefer a single base path for some order types, these return the same shapes as the primary endpoints:

• GET ProcessOrder/GetExistingCourtOrder/{workOrder} — court orders
• GET ProcessOrder/GetExistingDelivery/{workOrder} — delivery orders

Your other tracking calls — confirmed

Suggested polling flow

POST ProcessStatus/Search  (by file number or work order)
        |
        +--> read status, workOrder, type
        |
        v
GET {OrderType}/GetExisting/{workOrder}   (based on type)
        |
        +--> GET Notes/GetAll/{workOrder}
        +--> GET Diligence/Get/{workOrder}          (Process only)
        +--> GET ProofOfService/Get/{workOrder}     (Process only)
        +--> GET Invoice/Get/{workOrder}            (when applicable)
        +--> POST ProcessPDF/Search/{fileNumber}
        +--> GET ProcessPDF/Get/{workOrder}/{lineItem}

Important: Use the workOrderId returned from export (for example C123456), not the draft webOrderId (W123456). GetExisting only resolves exported Winserve work orders.

Q3 — Legacy v1 orders: `GetExisting/

v2 does not distinguish v1 vs v2 orders at the API layer. GetExisting looks up exported orders in the Winserve production tables for the authenticated customer. Legacy orders created before v2 should be readable through GetExisting when you use the correct order-type endpoint.

A 404 from GetExisting usually means one of the following:

1. Wrong order-type endpoint — for example calling ProcessOrder/GetExisting for a court order. Use the type field from ProcessStatus/Search, or try CourtOrder/GetExisting, PhotoCopyOrder/GetExisting, etc.
2. Draft web order id passed instead of work order id — W123456 will not resolve via GetExisting; only exported ids like C123456 will.
3. Customer scope mismatch — the token's customer code must match the order's customer.
4. Photocopy / WinCopy orders — use PhotoCopyOrder/GetExisting/{workOrder} (supports {workOrder}-{facilityId} when facility-scoped detail is needed).

What to do during the v1 → v2 transition

There is no separate "v1 fallback" endpoint. ProcessStatus/Search plus the correct GetExisting for the order type is the recommended approach.

3. Courtesy Copy — which endpoint?

Q4 — Which endpoint should we use to create a Courtesy Copy order?

Use POST CourtOrder/Create with job type 77 from GET CourtOrder/GetJobTypes.

Courtesy Copy is a court order workflow, not a records photocopy order and not a standalone messenger delivery order. This matches Tristar.Web, where courtesy copy options live on the court filing form and submit through the court order API.

Request shape

{
  "jobTypeCode": 77,
  "theirFileNumber": "REF-12345",
  "plaintiff": "...",
  "defendant": "...",
  "courtCode": "LASC",
  "caseNumber": "...",
  "department": "...",
  "room": "...",
  "copyType": "StandardCopy",
  "caseType": 5,
  "specialInstructions": "...",
  "documentsDescription": "...",
  "courtesyCopyDelivery": true,
  "export": true,
  "documents": [ ... ]
}

Courtesy copy flags on CourtOrder/Create

The web UI merges the "Deliver Courtesy Copy to the Court" checkbox into courtesyCopyDelivery on submit. For API purposes, set courtesyCopyDelivery: true for either standalone courtesy copy or filing with courtesy copy delivery.

Docs: CourtOrder.Create

Why not the other endpoints?

Tracking courtesy copy orders

After export, poll with ProcessStatus/Search and read milestones from GET CourtOrder/GetExisting/{workOrder} when type is Court.

4. Payments — v2 token permissions

Q5 — How do we get a v2 token that includes payment permissions?

Payment access on v2 is not controlled by JWT scopes (such as efiling:read / efiling:write). Those scope names are unrelated to the Payments endpoints.

Instead, v2 checks contact-level permissions in the Central DB APIUserPermissions table at request time — the same permission model as v1.

What is required

For GET Payments/GetAll/WP440 where WP440 is the authenticated contact's customer, the contact needs PermissionId = 4 (Payments) on a row keyed by:

• OwnedBy = API client tenant code (from X-Api-Key resolution)
• CustomerCode = acting customer code
• ContactCode = authenticated contact code

The same permission check applies to POST Payments/AddCreditCard and POST Payments/AddACH.

Docs: Payments.GetAll, Payments.AddCreditCard

What you need to do on your side

1. No API code change — the routes and token format are correct.
2. New contacts created through Registration/AddCustomer or Contact/Create receive Payments permission (PermissionId 4) automatically.
3. Existing contacts still need TriStar to grant Payments permission on the API contact you authenticate with (the same contact that has payment access in v1). This is an APIUserPermissions configuration change on TriStar's side, not a different API key type or OAuth scope.
4. Use the same contact credentials that have payment access in v1 when calling Auth/Token or Session/Create.
5. If you need to manage payments for customers other than the authenticated one, the contact also needs CanAccessAllCustomers (2).

Expected error when permission is missing

{
  "value": "You do not have permissions to access payment info",
  "statusCode": 401
}

This is the documented response when PermissionId 4 (or 2 for cross-customer access) is not present for the contact.

5. Follow-up: attorney field, WP prefix, and WinServe visibility

Canonical attorney property on ProcessOrder create

Use adjusterCode (integer code from GET Attorney/GetAll).

Optional: billToAdjusterCode (defaults to adjusterCode when omitted).

Do not send adjuster, attorney, or attorneyCode on ProcessOrder/Create — those names do not bind to this endpoint. (attorney is for PhotoCopy; attorneyCode is for Investigation.)

When export is true and adjusterCode is missing, the API returns 400 with "Adjuster code is required."

Docs: ProcessOrder.Create

Why exported WP440 orders are not in Import Webservice Orders

With export: true, v2 creates a live Winserve work order immediately. Those orders do not appear in WinServe's Import Webservice Orders queue (that queue is only for the legacy foreign-webservice import path).

Operations should search for the returned work orders (for example WP5038 / WP5039) as normal process work orders for customer WP440.

Docs: Order Lifecycle

What the WP vs LA work-order prefix means

The letters at the start of a work order come from the customer's branch company prefix, not from v1 vs v2. Customer WP440 uses a WP prefix; a different service-account customer/branch may use LA. Same export path — different branch numbering.

Multiple servees on ProcessOrder create

Multiple servees in one ProcessOrder/Create produce related work orders (suffix pattern …A, …B, …C, …).

The export response now returns:

• workOrderId — primary / first work order
• generatedWorkOrders — full list, each with workOrder and servee

Use generatedWorkOrders to track per-servee status via ProcessOrder/GetExisting/{workOrder}.

Reference links

• Order Lifecycle guide
• CourtOrder endpoints
• ProcessOrder endpoints
• DeliveryOrder endpoints
• PhotoCopyOrder endpoints
• ProcessStatus.Search
• Payments endpoints
• ReferenceData search endpoints