Add a message to a claim
Adds a note, documents or both to a claim you created. Garfield treats it like the claim's first message: it reads the message and takes the claim forward. Use it to correct a detail sent on the claim, give Garfield what it is waiting for when needs_attention is true, or send a document you did not have at creation. Garfield sends nothing, charges nothing and files nothing at court until the business confirms that step in Garfield. The claim's last_updated_at moves on at once, so a poll with updated_since picks the claim up.
You can add messages only while you can still create claims for the claim's entity, so the same 403 codes as POST /claims apply. A test key adds to its test claims.
Documents. Upload each file through POST /documents/upload-url with the claim's partner_claim_id. The same path and existence checks as POST /claims apply, and a file already attached to the claim fails with document_path_invalid. Upload it again to send a new copy.
Archived claims. A claim the business archived takes no more messages: the API returns 409 claim_archived.
Idempotency. Optional partner_message_id: a retry with the same value and body returns the first call's message_id and document_ids with already_existed: true and HTTP 200, adding nothing. The same value with a different body returns 409 idempotency_key_reused. Without partner_message_id, every call adds a message.
Request
POST/claims/:claim_id/messages
Responses
- 200
- 201
- 400
- 401
- 403
- 404
- 409
- 429
- 500
- 503
Replay: you already added a message with this partner_message_id. The response has the first call's message_id and document_ids, and Garfield adds nothing.
Garfield added the message.
The body is not valid. code is validation_failed (see details), invalid_json (not valid JSON) or body_required (no body, or Content-Type is not application/json). POST /claims and POST /claims/{claim_id}/messages also return document_path_invalid (a storage_path is not in the upload folder for this entity and partner_claim_id, or, on POST /claims/{claim_id}/messages, is already attached to the claim) or document_not_uploaded (a file in document_refs is not in storage).
Authentication failed. code gives the cause: auth_missing (no Authorization header), auth_invalid_format (the token has no pk_test_ or pk_live_ prefix, or its format is not valid), auth_revoked (Garfield revoked your partner account or rejected your application, or you revoked the key) or auth_bad_secret (the partner id, key id or secret is incorrect, or the prefix does not match the key's mode).
The key is valid but does not have access. code gives the cause: auth_partner_not_approved (Garfield has not approved your partner account yet, so only test keys work), entity_not_owned (the entity is not connected to you and is not your own), partner_disconnected (the entity disconnected from you, so you cannot read or write its claims) or entity_not_verified (Garfield has not verified the business yet, or rejected it, so uploads, claims and messages fail while every read still works).
You have not created a claim with this claim_id using a key of this mode.
idempotency_key_reused: you already sent this partner_message_id with a different body. Garfield added nothing. claim_archived: the business archived the claim, so you cannot add a message to it. claim_conflict: an internal id collision. This is rare. Send the same request again.
Too many requests. Each partner can send 120 requests per minute across all endpoints and keys, and only requests with a verified key count. Until Garfield approves a partner, the limit is 30 requests per minute. Requests that fail authentication count separately, 10 per minute for each IP address. Past that, fix the key before you send more requests. For the partner limit, wait the number of seconds in Retry-After, then retry. The API counts requests per minute as they arrive, so treat the limits as approximate.
Response Headers
The number of seconds to wait before you retry.
The maximum requests in each window, for the limit you exceeded.
Only on a 429, where it is 0. The API does not report a running count.
The window length in seconds, always 60. The API does not report how much of the current window is left. Only production sends this header.
A server error. code is internal_error. Retry with exponential backoff.
A dependency is temporarily unavailable. code is service_unavailable, or document_verification_failed when the API could not check an uploaded document in storage. Retry after Retry-After when the response has it, otherwise with exponential backoff.
Response Headers
The number of seconds to wait before you retry.