Discover the type, then write the record

Work records are switched on per workspace. Until they are, every write answers 409 NOT_AVAILABLE with feature: workRecords; reads still answer. A workspace may call its records Jobs, Calls, Policies or Matters. The API always says jobs: in the routes, the tools, the events and the fields.

Every record has a type, and the type decides its questions, its stages, its documents and its kinds of change. Read it first, with jobs:read:

A record pins its type’s revision when it is created, as typeRevision, and keeps it when the type is edited later. Read that revision to know which questions the record asks. typeRevision is set by the server: sending it is 400 FIELD_FORBIDDEN. A type that does not exist is 404 UNKNOWN_TYPE, and an archived one is 409 TYPE_ARCHIVED.

A record carries its answers in fields, keyed by the question’s key. Each value is a string in one form, or null to clear it. Several choices go in fieldLists and addresses in fieldAddresses. A key the type does not ask is refused.

GET /v1/jobs/{jobId}/validate-intake?at=activate (or draft, complete, bill) answers what the type still needs at that point, one issue per question: MISSING_ANSWER, INVALID_OPTION, FIELD_FORBIDDEN, TYPE_MISMATCH or MEMBER_UNKNOWN. It changes nothing.

A move that is missing answers is 409 MISSING_ANSWER, with each one in fields. A choice the question does not offer is 400 VALIDATION_FAILED, with that field’s code NOT_ALLOWED.

POST /v1/jobs (jobs:write) creates a draft. Give it a parentJobId to make a sub-job. A draft has no number and counts nothing.

Activation numbers the record, so it is an action request: POST /v1/actions/activateJob (actions:records, tool activate_job). A person approves it, or it runs at once only under a rule the owner set for that kind.

POST /v1/jobs/{jobId}/stage moves an active record. A draft is 409 JOB_NOT_ACTIVE; a completed or cancelled one is 409 JOB_CLOSED. close, reopen and discard are routes of their own. PATCH /v1/jobs/{jobId} needs the expectedUpdatedAt you read; if the record moved on, the answer is 409 TARGET_CHANGED.

POST /v1/jobs/{jobId}/contract-total sets the agreed total. An amount in another currency is 400 CURRENCY_MISMATCH. Once a deposit or progress invoice was raised against it, the total is locked: 409 CONTRACT_TOTAL_LOCKED.

Three calls, with jobs:write:

1. POST /v1/jobs/{jobId}/documents with fileName, contentType, size, an optional categoryId and your own createRequestId. The answer is the document, pending, and an upload: a signed URL, the headers to send with it, and when it expires.
2. PUT the bytes to that URL with exactly those headers, within 15 minutes.
3. POST /v1/jobs/{jobId}/documents/{docId}/complete. The server checks that the file is there, its size, and that its first bytes match its type.

A document ends attached or failed (missing, tooLarge, sizeMismatch, typeMismatch or expired); an upload never completed becomes expired. PNG, JPEG, WebP or PDF, up to 25 MB each; a record holds up to 50 documents and 250 MB, and a pending upload counts. Beginning again with the same createRequestId signs a fresh URL for the same document.

A document added through the API is never shown to the client by it. A person decides that in the console.

POST /v1/jobs/{jobId}/invoices (invoices:write and jobs:read) creates a draft invoice from the record. Nothing is sent: delivery stays an action request. POST /v1/bills/{billId}/allocations spreads a bill across records; allocations that add up to more than the bill are 400 ALLOCATION_EXCEEDS_TOTAL.

Changes such as a change order or an endorsement are drafted with POST /v1/jobs/{jobId}/adjustments, and edited or discarded while they are drafts. Issuing one and voiding one are action requests that always need a person: issueJobAdjustment and voidJobAdjustment, the second with a second factor.

Send an Idempotency-Key on every POST. The same key with the same body within 24 hours replays the first answer, with Idempotent-Replayed: true. The same key with another body is 409 IDEMPOTENCY_CONFLICT; while the first request still runs it is 409 IDEMPOTENCY_IN_FLIGHT with Retry-After. A document upload also carries its own createRequestId.

The list, GET /v1/jobs, reads with invoices:read. Applying a proposed setup (applyWorkConfig, actions:admin), attaching a file the approver chooses (attachJobDocument), deleting a record (deleteJob) and sending a record’s link to its client (sendJobLink) are action requests that always need a person. A message to the client, POST /v1/jobs/{jobId}/messages, also needs actions:deliver and returns a pending action, not a sent message.

Subscribe to job.created, job.updated, job.stageChanged, job.moved, job.adjustmentIssued, job.adjustmentVoided and workConfig.changed. A job in an event is a narrow view: its number, type, label, status, stage, client, currency, totals, and the answers the type marks for the client. Sensitive and internal answers, lists, files, addresses, emails, phones, notes and assignees never leave. Stage labels arrive inside the untrusted-data envelope.

Towing. Create a Call with its vehicle and pickup answers, ask to activate it, move it through its stages, upload the signed authorization before you complete it, then create the invoice from the Call.

Insurance. Create a Policy with its policy type and premium answers, validate at activate, and ask to activate it. A mid-term endorsement is a change drafted on the Policy and issued by a person.

Legal. Read the Matter type’s revision, create the Matter with its answers, upload the signed engagement letter, and listen for job.stageChanged to follow it.