Insurer acknowledges receipt of the referral

POST 
/referrals/:id/acknowledge-insurer

Records the insurer's acknowledgement that they received the referral packet and are preparing a quotation. Transitions the referral from sent_to_insurer to quotation_pending. Called by the insurer inbound webhook or by a ZFA reviewer noting the insurer has confirmed receipt out-of-band. Requires the referral:insurer:ack permission.

Request

Responses

200

Referral moved to quotation_pending.

201

Resource created. Body follows the shared { data, meta } envelope; data is the newly-created resource.

400

The request payload failed validation. error.details lists the offending fields with human-readable messages and the class-validator constraint that fired. Fix the payload and retry — this is not a transient failure.

401

Missing or invalid access token.

403

Caller lacks the required permission.

404

Referral not found.

409

Referral is not in sent_to_insurer state.

422

The request is syntactically valid but violates a business invariant — a referral state transition not permitted from the current status, a wallet withdrawal exceeding the available balance, or a POP being confirmed before it has been ZFA-verified. error.code is one of INVALID_TRANSITION, INVARIANT_VIOLATION, or a domain-specific value; error.message explains the invariant.

429

Rate limit exceeded. Global default is 120 requests/minute per IP; auth-flow, OTP, self-registration, WebAuthn, IRA lookup, and public-lead endpoints carry tighter per-endpoint limits. Retry after the delay indicated by the Retry-After header.

Response Headers

Retry-After

Seconds to wait before retrying.

500

Unhandled server error. The response carries a meta.requestId correlator you can hand to platform operations to trace the failure through structured logs and the hash-chained audit trail. Retry with the same Idempotency-Key header if the endpoint accepts idempotency.