VocalDocscontracts 1.65.0

Attest a pre-call hook for PHI

POST /v1/pre-call-hooks/{hook_id}/attest-phi

PropertyValue
Operationattest_pre_call_hook_phi
GroupPre-call hooks
Scopehooks:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited dispatch.pre_call_hook.attest_phi (mutation)
Released in1.52.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Records an owner's attestation that the hook's endpoint is the Organization's own system or covered by a BAA (1.52.0; call-lifecycle-hooks-and-events.md section 2.6), which a PHI-mode Organization requires before status: active, and answers the hook with phi_attested_at and phi_attested_by. Session only: the api refuses every API key with forbidden, and a Member who is not an owner with forbidden and the detail owner_required. A change of the URL clears the attestation. Audited as dispatch.pre_call_hook.attest_phi.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the hooks:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/pre-call-hooks/pch_.../attest-phi" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint_covered": true }'

Parameters

NameInTypeRequiredDescription
hook_idpathPreCallHookIdyesThe id of a pre-call hook: pch_ and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: PreCallHookPhiAttestationRequest.

FieldTypeRequiredDescription
endpoint_coveredtrueyesThe owner's statement that the endpoint is the Organization's own system or covered by a BAA.

Responses

StatusContent typeShapeError codes
200application/jsonPreCallHook
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 200 answer

The shape is PreCallHook.

FieldTypeRequiredDescription
allowed_agent_idsarray of AgentIdyesAgents besides the routed one whose published versions a response may select; empty allows only versions of the routed Agent.
consecutive_failuresintegeryes
created_atTimestampyes
defaultPreCallHookDefault or nullyes
directionsarray of PreCallHookDirectionyes
idPreCallHookIdyes
object"pre_call_hook"yes
on_failurePreCallHookOnFailureyes
phi_attested_atTimestamp or nullyesWhen an owner attested the endpoint for PHI; null before.
phi_attested_byMemberId or nullyes
previous_secret_expires_atTimestamp or nullyes
previous_secret_hintstring or nullyes
revisionintegeryes
scopePreCallHookScopeyes
secret_hintstringyesThe last four characters of the current secret.
statusPreCallHookStatusyes
timeout_msinteger or nullyesThe deadline of a request; null for the default of each direction.
updated_atTimestampyes
urlstringyesThe endpoint.