> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify a caller before disclosure

> Make the agent prove a caller's identity before it reads back account details or takes a sensitive action.

When an agent can look up orders, balances, or appointments, you don't want it reading those
back to *anyone* who calls. **Caller verification** is a deterministic guardrail: the agent
must verify identity before it discloses sensitive fields or runs a write action. Unlike a
prompt instruction, this is enforced, not suggested. All paths are relative to
`https://builder.flowyte.com/api/v1`.

<Note>
  Authenticate with `Authorization: Bearer flowyte_sk_…`. Both endpoints below are **replace** (`PUT`) — send the full list each time.
</Note>

It comes together in three parts:

1. A **verifier skill** that checks the caller's answers against your system of record.
2. A **caller-verification config** that ties a verification method to that verifier.
3. A **guardrail** plus per-skill flags that block disclosure until the caller is verified.

## What you'll use

| Action                             | Endpoint                                       | Scope                                  |
| ---------------------------------- | ---------------------------------------------- | -------------------------------------- |
| Create the verifier skill          | `POST /agents/{id}/skills`                     | `skills:write`                         |
| Read / replace verification config | `GET` · `PUT /agents/{id}/caller-verification` | `guardrails:read` · `guardrails:write` |
| Read / replace guardrail policies  | `GET` · `PUT /agents/{id}/guardrails`          | `guardrails:read` · `guardrails:write` |
| Gate a disclosure skill            | `PATCH /agents/{id}/skills/{id}`               | `skills:write`                         |

## Verification methods

| `method`          | The caller proves identity with            |
| ----------------- | ------------------------------------------ |
| `dob_postcode`    | date of birth + postcode                   |
| `account_pin`     | an account PIN                             |
| `otp_sms`         | a one-time code sent by text               |
| `knowledge_based` | answers only the account holder would know |

<Note>
  `otp_sms` sends a text, which requires per-organization 10DLC brand and campaign registration
  before sends are allowed.
</Note>

<Steps>
  <Step title="Create the verifier skill">
    The verifier is a skill (commonly `db_query` or `http_webhook`) that takes the caller's claimed
    identity plus a secret and returns whether they match. Capture its `id` — you'll reference it
    as `verifierSkillId`.

    ```bash theme={null}
    curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/skills \
      -H "Authorization: Bearer $FLOWYTE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Verify identity",
        "description": "Confirm the caller by date of birth and postcode.",
        "skillType": "http_webhook",
        "executionConfig": { "url": "https://api.example.com/verify", "method": "POST" }
      }'
    ```
  </Step>

  <Step title="Wire the verification config">
    Tie a method to the verifier. `tokenTtlSeconds` controls how long a verification stays valid
    on the call; `maxAttempts` caps retries; `stepUpFor` names actions that demand a re-check even
    after basic verification.

    ```bash theme={null}
    curl -X PUT https://builder.flowyte.com/api/v1/agents/$AGENT_ID/caller-verification \
      -H "Authorization: Bearer $FLOWYTE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '[
        {
          "method": "dob_postcode",
          "requiredFields": ["date_of_birth", "postcode"],
          "verifierSkillId": "'$VERIFIER_SKILL_ID'",
          "tokenTtlSeconds": 600,
          "maxAttempts": 3,
          "stepUpFor": ["refund"]
        }
      ]'
    ```
  </Step>

  <Step title="Add the guardrail and gate your skills">
    Add a `verify_before_disclose` policy, then mark every skill that returns sensitive data with
    `requiresVerifiedIdentity: true`. Use `verificationLevel` (`basic` or `step_up`) for
    higher-risk actions, and `allowedFields` to cap what may be read back.

    <CodeGroup>
      ```bash Guardrail theme={null}
      curl -X PUT https://builder.flowyte.com/api/v1/agents/$AGENT_ID/guardrails \
        -H "Authorization: Bearer $FLOWYTE_API_KEY" \
        -H "Content-Type: application/json" \
        -d '[
          { "policyType": "verify_before_disclose", "appliesToSkillType": "shopify", "isEnabled": true }
        ]'
      ```

      ```bash Gate a skill theme={null}
      curl -X PATCH https://builder.flowyte.com/api/v1/agents/$AGENT_ID/skills/$SKILL_ID \
        -H "Authorization: Bearer $FLOWYTE_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{ "requiresVerifiedIdentity": true, "verificationLevel": "basic" }'
      ```
    </CodeGroup>
  </Step>
</Steps>

<Warning>
  Verification is enforced at runtime, but it only protects skills you actually gate. Audit every
  skill that returns account data and set `requiresVerifiedIdentity`. Changes apply on **publish**.
</Warning>

Related: [Guardrails](/concepts/guardrails) · [Skills](/concepts/skills) · [Draft vs published](/get-started/draft-vs-published)