Mark an agent as KYC-verified
POST/agents/:id/kyc/verify
Promotes the agent to verified KYC state (and typically to active status) after every mandatory document has been verified. Sets a re-verification expiry based on the kyc.verification_validity_years policy (default 2 years). Records agent.kyc.verify in the audit log. Requires the agent-kyc:verify permission.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 500
Updated Agent with verified KYC status.
One or more mandatory documents are missing or not yet verified.
Missing or invalid access token.
Caller lacks the required permission.
Agent not found.
The request conflicts with the current state of the target resource — a duplicate unique field on registration, an idempotency-key replay with a different payload, or a webhook eventId that has already been processed. error.code may be CONFLICT or IDEMPOTENCY_CONFLICT depending on the cause.
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.