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.

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 →