Skip to main content
The Case Management API lets you attach evidence, send messages to paywise, and answer questions raised during case processing. Each document belongs to the resource it supports: a claim, rental agreement, enforceable title, message, or request-to-client answer. Claim documents use the stable claim path /v2/claims/{claim_id}/documents/; review movement never changes that URL. Your integration sends the file contents to paywise. A successful upload creates the document and attaches it to its parent in one transaction; malware scanning and page processing continue asynchronously.

​
Uploading documents

Choose the format that fits the operation: Supply exactly one content source per document. Multipart files are accepted only by the dedicated document endpoints; inline documents use base64. Base64 content may be line-wrapped. There is no upload-by-URL option: a url field returns 400 as an unknown field. If your source system provides a download link, retrieve the file in your integration and upload its bytes. Existing document IDs cannot be used as upload input, and there is no standalone upload to attach later. Use an Idempotency-Key for each create command. A dedicated document upload returns 201 with the document resource and a Location header. Keep its id so you can read its processing status. For request examples, see Manage documents.

​
File validation and limits

The API validates content before creating the document. Invalid content returns 400 on file or base64, or on documents[i].base64 for an inline attachment. Content errors include unsupported, corrupt, encrypted, and page_limit_exceeded; invalid base64 and oversized files also fail during upload. Correct the input before submitting a new command. The split between synchronous and asynchronous checks is fixed: the byte sniff (unsupported, corrupt), the PDF structure checks (encrypted, page_limit_exceeded), size, and base64 decoding run synchronously and answer 400 — no document is created. Only the malware scan and page processing run asynchronously after the 201, and they surface as the document’s rejected or failed status. The bytes are stored before the response: if document storage is briefly unavailable, the upload — or the command that carries inline documents — answers 503 service_unavailable with Retry-After: 1, creates nothing, and releases its Idempotency-Key; retry the same command with the same key. A command carries at most 20 documents; the 21st is refused before any document is decoded. A multipart upload sends each part once: a repeated type, filename, base64, or file part is 400 on that part name with code duplicate_part. A multipart body that ends before the file part is complete reads as a missing file and is 400 on file. The supplied filename and media type do not determine the file format. paywise removes path components and control characters from filename and adjusts its extension to match the detected content, so the returned name can differ from the one you sent.

​
Processing and downloads

An accepted upload starts as pending. Its status describes whether the file is safe and available to use: failure_reason is populated only for failed documents. Its values are page_limit_exceeded, encrypted, corrupt, unsupported, or processing_failed; it is null for other statuses. Follow status and updated_at through the document resources. Document processing does not emit public webhooks. download_url is null until the document is ready, and stays null for rejected and failed documents because their bytes are no longer stored. Once available, it points to an authenticated API download route: send your Bearer credential just as you would for other reads. A download before readiness, or of a rejected/failed document, returns 404. The API streams the file as an attachment with nosniff and no-store headers. Use this route instead of constructing or saving a storage-provider URL. Every download route — documents, mandate history attachments, request attachments, and statement files — serves Accept: */*, application/octet-stream, application/pdf, image/*, and application/json; any other value such as text/html is 406 not_acceptable. An object that is missing in storage is 404 not_found; a storage fault is 503 service_unavailable with Retry-After: 1, so retry after the interval. DELETE of an unknown claim, rental-agreement, or enforceable-title document is a neutral 404: the response does not reveal whether the document ever existed under another parent.

​
Replacing an attachment

Documents have no PATCH or ingestion retry operation. To replace a file, delete it from its parent, then upload the replacement with a new idempotency key. The replacement has its own document ID and processing status. Retrying an upload whose HTTP response was lost is different: resend the same command with the same key to recover its result. The parent determines when documents can be added or deleted: Mutations outside these windows return 409. Finalizing an order does not wait for scanning; poll its evidence before finalization if you need to be able to replace a file that fails processing. Reviewers can access the bytes only after scanning and page processing succeed.

​
Rental and title evidence

Use the document route for the resource the evidence describes: rental_agreement and enforceable_title are rejected with invalid_choice on the generic claim document route. Creating a second file in an occupied primary slot returns 409; delete the old file before uploading its replacement. Rental-agreement documents are optional at finalization. Keep each rental month’s statement on its claim; the receivable claim’s subject-matter-or-document readiness rule still applies. A titled claim requires its primary title document at finalization, with status pending or ready.

​
Messages

Send a message below /v2/orders/{order_id}/messages/ or /v2/mandates/{mandate_id}/messages/ with title, body, and optional inline documents. The 201 response contains the message resource, including its id, editable flag, and attachments. Supported HTML in body is sanitized; a body that is empty after sanitization is 400 on body with code blank, on create and on PATCH alike. body follows the multi-line rule: TAB, LF, and CR are accepted, other control characters are 400 with code control_characters. An API-created message belongs to the company’s API principal, so rotating the API key does not change ownership. While editable is true, you can update its title or body and add or delete documents through the message’s document routes. Staff review closes that window; portal-authored messages and paywise replies cannot be edited through the API. Withdrawn, rejected, merged, and expired orders reject message changes with 409 (order_expired for an expired draft). When messaging is disabled for a mandate, creating or editing a message there and adding or deleting its documents answer 409 conflict (Messages are disabled for this mandate.). Messages are written below an order or a main case: creating one below a subcase answers 404 (No mandate found for the given reference.), while an existing subcase thread stays readable. Message creation acknowledges receipt while attachments are still processing. paywise takes the message into case processing right away, as it does a message written in the paywise portal: it hands the attachments over as they are at that moment and leaves out files already failed or rejected. Replace such a file while the message remains editable if the evidence still needs to be sent. Downloads through the API still require ready. Published paywise replies appear in the message collection; internal notes do not. The order.message.created and mandate.message.created events acknowledge client-authored messages received by paywise, so they are not notifications of a paywise reply. Read the thread to retrieve replies.

​
Requests to client

A request to client is a published question from paywise that needs an answer. Read it below /v2/orders/{order_id}/requests-to-client/ during order review, or /v2/mandates/{mandate_id}/requests-to-client/ for a mandate. Use the parent identified by the request; order and mandate UUIDs are not interchangeable. The request includes allowed_answer_types, question_attachments, and its current answer. Download question attachments through their authenticated download links. Submit the answer once at the request’s /answer/ endpoint; the 200 response is the updated request. A second answer with a different idempotency key returns 409. Sending an ordinary message does not answer the request. Build the payload for the advertised answer type: booking_date is forbidden for all other answer types. Inline documents are accepted only on fileupload, freetext, yes-no-freetext-on-no, and yes-with-date-no-freetext-on-no answers; on any other type they are 400 on documents with code not_allowed. They use the same base64 format and limits as other uploads. After answering, files can be added or deleted through /answer/documents/ while the answer remains editable. text on the free-text types and additional_comment are plain text: markup is removed and HTML entities are decoded before validation. A value that is empty after stripping is 400 with code blank; markup that does not converge to plain text is 400 with code invalid. Both fields follow the multi-line rule (TAB, LF, and CR accepted; other control characters are control_characters). For order requests, answering creates a staff review task. Once all published requests on the order are answered, claims waiting for a client response return to review. This does not wait for attachment processing. Closed orders reject new answers and answer-document changes with 409. For mandate requests, staff notification is scheduled immediately, while downstream answer processing waits for all attached documents to be ready. Any failed or rejected attachment blocks that processing. Delete it and upload a corrected replacement while the review task is open. Files added after the initial answer are subject to the same processing rule. See Messages and client requests for request examples. To follow the case as a whole, use mandate history: published history entries can link messages, requests, emails, or single-mandate statements in related_resources. An underlying record alone does not create a history entry.