VocalDocscontracts 1.65.0

Attest a Connection for PHI

POST /v1/connections/{connection_id}/attest-phi

PropertyValue
Operationattest_connection_phi
GroupConnections
Scopeintegrations:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited integrations.connection.attest_phi (mutation)
Released in1.60.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Records an owner's attestation that the Connection's system is the Organization's own or covered by a BAA, with the agreement reference, and answers the Connection with phi_attestation (1.60.0; integrations-operations.md section 2, rule 1). Session only: every API key is refused with forbidden, and a Member who is not an owner with the detail owner_required. A Connector whose manifest says phi_capable: false, or an MCP server with auth: none, is validation_failed with connection_not_phi_capable. Vocal records the statement and does not verify it.

Request

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

curl -X POST "$VOCAL_API/v1/connections/con_.../attest-phi" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "basis": "own_system" }'

Parameters

NameInTypeRequiredDescription
connection_idpathConnectionIdyesThe id of a Connection: con_ 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: ConnectionPhiAttestationRequest.

FieldTypeRequiredDescription
agreement_referencestringnoThe agreement covering the system; required for baa.
basisPhiAttestationBasisyes

Responses

StatusContent typeShapeError codes
200application/jsonConnection
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopeconnection_revoked, idempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 200 answer

The shape is Connection.

FieldTypeRequiredDescription
allowed_environmentsarray of EnvironmentyesThe environments whose runs may use it; live only by default. A test run against a Connection that does not allow test executes the Connector's mock (integrations.md section 3).
auth_strategyConnectionAuthStrategyyes
authorized_atTimestamp or nullyes
base_urlConnectionBaseUrl or nullyes
connector_idConnectorId or nullyesThe Connector; null for an MCP server.
connector_majorinteger or nullyesThe major version of the Connector's manifest the Connection pins; null for an MCP server.
created_atTimestampyes
enabled_toolsarray of ConnectorToolNameyesThe Connector's tools the Organization allows, which set the scopes requested (integrations.md section 10); empty for an MCP server, whose registration's allowed_tools govern.
external_accountstring or nullyesThe external account authorized (a tenant id, an instance URL); null before.
granted_scopesarray of VendorScopeyesThe scopes the vendor granted at the last authorization; empty before.
idConnectionIdyes
mcp_server_idMcpServerId or nullyesThe MCP server registration whose credential the Connection holds; null for a Connector.
nameConnectionNameyes
object"connection"yes
organization_idOrganizationIdyes
originConnectionOriginyes
phi_attestationConnectionPhiAttestation or nullyesThe PHI attestation, or null; only an attested Connection may receive PHI.
requested_scopesarray of VendorScopeyesThe union of the scopes of enabled_tools; nothing more is requested.
revisionintegeryesCounts writes to the Connection; returned as the ETag and required in If-Match.
revoked_atTimestamp or nullyes
sandboxbooleanyesTrue for a vendor sandbox, which may allow test; a test Call never books a real appointment.
secret_hintstring or nullyesThe last characters of the stored key or token, or null; never the secret.
secret_versionintegeryesCounts the secrets stored; 0 before the first. A refresh write-back compares and sets it.
senderConnectionSender or nullyesThe sender of a messaging Connection; null otherwise.
statusConnectionStatusyes
status_reasonConnectionStatusReason or nullyesNull while active.
updated_atTimestampyes