Mint a signed URL to upload a supporting document

POST 
/documents/upload-url

Two URLs, two requests. POST /documents/upload-url (this endpoint) returns a short-lived (15 min) signed upload_url; you then PUT the file bytes to that upload_url (a Google Cloud Storage URL, not a Garfield endpoint). This endpoint never receives the file itself.

The storage path is scoped to the entity and to a key derived deterministically from (partner_id, partner_claim_id). Upload BEFORE calling POST /claims with the same partner_claim_id; then reference each returned storage_path in the claim's document_refs.

Uploading to the returned upload_url

PUT the file with the exact headers from required_headers (the x-goog-content-length-range header caps the size: default 50 MB, or your max_bytes). The URL is PUT-only and its Content-Type is signed in, so opening it in a browser returns MalformedSecurityHeader, which is expected.

curl -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" \
  -H "x-goog-content-length-range: 0,52428800" \
  --data-binary @invoice.pdf

Full walkthrough: Upload supporting documents

Request

Responses

201

A signed upload URL was created.

400

The request body was malformed or failed validation. code is one of validation_failed (schema validation; see details), invalid_json (body was not valid JSON), or body_required (no JSON body: sent with a missing body or a Content-Type other than application/json).

401

Authentication failed. The code distinguishes the cause: auth_missing (no Authorization header), auth_invalid_format (malformed token), auth_unknown_partner (no such partner), auth_revoked (partner or key revoked), auth_bad_secret (bad key id or secret).

403

The partner is authenticated but not authorised. code is auth_partner_not_approved (the partner account is still pending approval; no endpoint will work until it is approved), entity_not_owned (no connection to the entity), or partner_disconnected (the entity disconnected the partner).

404

The referenced entity does not exist.

429

The per-partner rate limit (120 requests per minute, shared across all partner endpoints) was exceeded. Inspect Retry-After and the X-RateLimit-* headers before retrying.

Response Headers

Retry-After

Seconds to wait before retrying.

X-RateLimit-Limit

The request ceiling for the window.

X-RateLimit-Remaining

Requests remaining in the current window.

X-RateLimit-Reset

Unix epoch milliseconds when the window resets.

500

An unexpected server error occurred. The message is always the generic string Internal error; key on code, not message.

503

A dependency the request relies on is temporarily unavailable. The partner did nothing wrong; retry after the delay in Retry-After.

Response Headers

Retry-After

Seconds to wait before retrying.