Concepts & how things work

The reference tells you what to send. This page explains why — how a call moves through verification, what enrolling a voice actually does, and what each response property means.

The call lifecycle

A reseller works inbound calls for a child institution. Each call is identified by a voiceId — Pindrop's identifier for that call's audio, and the handle you pass to every call-scoped endpoint.

1. Assign — POST /external/calls/assign links an inbound call (by phone number or existing voiceId) to a member (personId) and returns the voiceId.
2. Queue — GET /external/calls/queue lists calls awaiting verification, with optional search and date filters.
3. Inspect — GET /external/calls/{voiceId}/details returns the full call record: enrollment/verification flags, risk, and the Pindrop event log.
4. Decide — POST …/enroll to accept the caller's voice, or POST …/reject-voice to reject it.

How voice enrollment works

Enrolling a voice (POST /external/calls/{voiceId}/enroll) is how a reseller manually authenticates a caller and tells Pindrop to trust and keep that caller's voiceprint. A single call does several things atomically:

• Records a verification for the member, tagged with the validationType you supplied (voice, OTP, KBA, …).
• Tells Pindrop the interaction succeeded — it sends account-interaction feedback keyed by the account alias {institutionKey}-{personId} against this voiceId, with status SUCCESSFUL. This is what lets Pindrop enroll and reuse the voiceprint on future calls.
• Applies the “Green Manual Authentication” policy to the call. This signals to Pindrop's call-end webhook that the enrollment should be preserved even if an automated voice-match rule would otherwise reject it.
• Writes two activity records — AcceptCallerVoice (the reseller explicitly accepted the voice) and FullAuthentication (the caller is fully authenticated). The FullAuthentication activity is what stops the call-end webhook from discarding the voiceprint.

curl -X POST https://api.getconfirmed.org/external/calls/<voiceId>/enroll \
  -H "SsoToken: <sso-token>" \
  -H "InstitutionKey: acme-cu" \
  -H "RequestedBy: jdoe" \
  -H "Content-Type: application/json" \
  -d '{ "personId": "00123", "validationType": "VoiceAuth", "notes": "Verified by agent" }'

→ { "success": true }

Voice authentication thresholds

Separately from the manual /enroll flow above, Pindrop runs its own passive voice biometrics on call audio. Two distinct checks govern this — one for creating a voiceprint (enrollment) and one for matching against an existing voiceprint (verification). Both require a low device risk_rating.

Rejecting & un-enrolling a voice

POST /external/calls/{voiceId}/reject-voice is the inverse. It notifies Pindrop of a FAILED interaction, records a RejectCallerVoice activity, and — importantly — un-enrolls every prior manual authentication for that member: each earlier FullAuthentication activity is moved to FullAuthenticationUnenrolled, so Pindrop discards the previously trusted voiceprint. Use it when a caller's identity can't be trusted.

Call detail properties

Selected fields returned by GET /external/calls/{voiceId}/details. The reference lists the full schema; these are the ones whose meaning isn't obvious.

Interpreting the validation status

Our own dashboard shows the agent a single color-coded validation status for each call — a traffic-light that tells them how to proceed. That status is derived entirely from metaData.pindropPolicies (the policies Pindrop applied to the call). If you build your own agent UI, reproduce the same logic so your status matches ours.

The rule is a simple case-insensitive keyword match with a fixed precedence — the first rule that matches wins:

Two more states are not driven by a policy string — they're behavioural:

Activity status reference

The status on a call (and on individual activity records) is one of the following.

Validation types

The validationType you send when enrolling records how the caller was verified.

Open the API reference →