naftiko: 1.0.0-alpha2
info:
  label: Twilio Identity and Fraud Prevention
  description: Capability combining Twilio Lookup for phone intelligence and Twilio Verify for identity verification. Used
    by security engineers, fraud prevention teams, and platform architects to validate users, detect fraud, and enforce multi-factor
    authentication workflows.
  tags:
  - Twilio
  - Identity
  - Fraud Prevention
  - Phone Verification
  - Security
  - Two Factor Authentication
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    TWILIO_ACCOUNT_SID: TWILIO_ACCOUNT_SID
    TWILIO_AUTH_TOKEN: TWILIO_AUTH_TOKEN
capability:
  consumes:
  - type: http
    namespace: twilio-lookup
    baseUri: https://lookups.twilio.com/v2
    description: Twilio Lookup API v2
    authentication:
      type: basic
      username: '{{TWILIO_ACCOUNT_SID}}'
      password: '{{TWILIO_AUTH_TOKEN}}'
    resources:
    - name: phone-numbers
      path: /PhoneNumbers/{PhoneNumber}
      description: Query phone number intelligence
      operations:
      - name: fetch-phone-number
        method: GET
        description: Look up phone number intelligence data
        inputParameters:
        - name: PhoneNumber
          in: path
          type: string
          required: true
          description: Phone number in E.164 format
        - name: Fields
          in: query
          type: string
          required: false
          description: Comma-separated data packages (validation, line_type_intelligence, caller_name, sim_swap, identity_match,
            sms_pumping_risk)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: twilio-verify
    baseUri: https://verify.twilio.com/v2
    description: Twilio Verify API v2
    authentication:
      type: basic
      username: '{{TWILIO_ACCOUNT_SID}}'
      password: '{{TWILIO_AUTH_TOKEN}}'
    resources:
    - name: verifications
      path: /Services/{ServiceSid}/Verifications
      description: Send verification codes
      operations:
      - name: start-verification
        method: POST
        description: Start a verification by sending a code
        inputParameters:
        - name: ServiceSid
          in: path
          type: string
          required: true
          description: Verify Service SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: form
          data:
            To: '{{tools.to}}'
            Channel: '{{tools.channel}}'
      - name: fetch-verification
        method: GET
        description: Fetch a verification status
        inputParameters:
        - name: ServiceSid
          in: path
          type: string
          required: true
          description: Verify Service SID
        - name: Sid
          in: path
          type: string
          required: true
          description: Verification SID or phone number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: verification-checks
      path: /Services/{ServiceSid}/VerificationCheck
      description: Check verification codes
      operations:
      - name: check-verification
        method: POST
        description: Check a verification code
        inputParameters:
        - name: ServiceSid
          in: path
          type: string
          required: true
          description: Verify Service SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: form
          data:
            To: '{{tools.to}}'
            Code: '{{tools.code}}'
  exposes:
  - type: rest
    port: 8081
    namespace: twilio-identity-api
    description: Unified REST API for identity verification and fraud prevention.
    resources:
    - path: /v1/phone-numbers/{phone_number}
      name: phone-number-lookup
      description: Look up phone number intelligence for fraud detection
      operations:
      - method: GET
        name: lookup-phone-number
        description: Get phone number intelligence including carrier, line type, and fraud risk
        call: twilio-lookup.fetch-phone-number
        with:
          PhoneNumber: rest.phone_number
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/verifications
      name: verifications
      description: Send verification codes for identity confirmation
      operations:
      - method: POST
        name: start-verification
        description: Start a verification workflow
        call: twilio-verify.start-verification
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/verification-checks
      name: verification-checks
      description: Check submitted verification codes
      operations:
      - method: POST
        name: check-verification
        description: Verify a code to confirm user identity
        call: twilio-verify.check-verification
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9091
    namespace: twilio-identity-mcp
    transport: http
    description: MCP server for AI-assisted identity verification and fraud prevention.
    tools:
    - name: lookup-phone-number
      description: Look up phone number intelligence including validation, carrier, line type, SIM swap status, and fraud
        risk score
      hints:
        readOnly: true
        openWorld: true
      call: twilio-lookup.fetch-phone-number
      with:
        PhoneNumber: tools.phone_number
      outputParameters:
      - type: object
        mapping: $.
    - name: verify-send-code
      description: Send a verification code to a user via SMS, voice, WhatsApp, or email to confirm their identity
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: twilio-verify.start-verification
      outputParameters:
      - type: object
        mapping: $.
    - name: verify-check-code
      description: Check a verification code submitted by a user to complete identity confirmation
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: twilio-verify.check-verification
      outputParameters:
      - type: object
        mapping: $.
    - name: fetch-verification-status
      description: Fetch the current status of a verification attempt
      hints:
        readOnly: true
        openWorld: false
      call: twilio-verify.fetch-verification
      outputParameters:
      - type: object
        mapping: $.