Convert an inquiry into a full Referral
POST/admin/zfa-direct/inquiries/:id/convert-to-referral
The assigned ZFA-desk owner picks an InsurerProduct (and optionally a ProductPlan) that matches the client's request, and this endpoint materialises a Referral with channelSource set to zfa_direct (for admin-created inquiries) or client_self_service (for public-form inquiries). The inquiry is then closed as converted and the referral takes over the downstream workflow — quotation, POP, policy, commission (which will land in the ZFA house wallet under Phase 4).
Request
Responses
- 200
- 201
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 500
Newly-created Referral record; inquiry marked converted.
Resource created. Body follows the shared { data, meta } envelope; data is the newly-created resource.
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.
Missing, malformed, or expired authentication token. Log in via POST /auth/login (or refresh via POST /auth/refresh) and retry with a fresh Authorization: Bearer <accessToken> header.
The authenticated caller does not carry the required permission or is scoped out of this resource by the object-authorization service (e.g. an agent trying to view another agent's referrals). Grant the missing permission via a role change or scope the query to resources the caller owns.
The referenced resource does not exist or is not visible to the caller. Note: object-level scoping is opaque — a resource you cannot see is indistinguishable from a resource that does not exist.
Inquiry already converted.
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.
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
Seconds to wait before retrying.
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.