HITL

Create an identity challenge

Start a cross-channel Proof of Me identity challenge. The bot dispatches a CONFIRM/DENY prompt to the account owner on a channel different from the member's; the result is reported back to the member.

post/api/v1/identity-challenges

Request

  • Base URL: https://api.proof.holdings
  • URL: https://api.proof.holdings/api/v1/identity-challenges
  • Auth: one of:
    • HTTP bearer
    • API key in cookie auth_token

Request body

circle_idstring required

Circle that holds the member

member_idstring required

Enrolled member initiating the check

suspicious_channel'telegram' | 'whatsapp'

Channel the member was reached on; defaults to the member's first verified channel. The CONFIRM is routed cross-channel from it.

Example request

{
  "circle_id": "507f1f77bcf86cd799439011",
  "member_id": "507f191e810c19729de860ea"
}

Response

Identity challenge created

idstring required
status'pending' | 'confirmed' | 'denied' | 'cancelled' | 'failed' | 'expired' | 'revoked' | 'suspended' required

The one status every read reports. pending — waiting for the person being checked; confirmed — they confirmed; denied — they denied; cancelled — whoever started the check withdrew it; failed — the check could not be delivered; expired — nobody answered in time; revoked / suspended — the confirmation's proof was revoked or suspended (POST /proofs/{proof_id}/revoke or /suspend; revoking a denial's proof leaves it denied), or — revoked only — the member being checked was removed from the Circle while the check was still pending, which leaves proof_id null. Removing a member is not guaranteed to revoke a confirmation they already gave; revoke that one by its proof_id. A proof that merely reached its own expiry still reads confirmed; whether its token is still valid is POST /proofs/validate's answer.

channelstring

Channel the CONFIRM was dispatched on (GET)

confirm_channelstring

Channel the CONFIRM was dispatched on (POST)

single_channel_warningboolean

True when the account holder has only one channel, so the CONFIRM ran on the same channel as the suspicious contact (degraded)

circle_idstring nullable

The Circle the check belongs to (GET)

is_drillboolean

True for a drill (scheduled, or started from the dashboard) rather than a real check (GET)

proof_idstring nullable

Public handle of the decision's proof — what POST /proofs/{proof_id}/revoke takes. Null until a decision minted one (GET).

proof_tokenstring nullable

Signed proof token, present once the person being checked decided

created_atstring

ISO 8601 timestamp

resolved_atstring nullable

ISO 8601 timestamp of the decision — the CONFIRM, the DENY, the cancellation or the delivery failure — or null while the check is unanswered and after a timeout.

expires_atstring

ISO 8601 timestamp

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "status": "pending",
  "channel": "telegram",
  "confirm_channel": "telegram",
  "proof_id": "ph_ctl_0123456789abcdef0123456789abcdef"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.