Telefónica KYC Match API

openapi: 3.0.3
info:
  title: Telefónica Status Device Roaming KYC Match API
  description: The Device Roaming Status API verifies the roaming status of a SIM-based device using carrier network data, without relying on GPS or risking identity information exposure. Enables fraud detection, content geo-restriction, and compliance workflows. Based on CAMARA open standards. Available in Spain and Brazil.
  version: 0.5.0
  contact:
    url: https://opengateway.telefonica.com/en/apis/device-roaming-status
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://opengateway.telefonica.com/v1
  description: Telefónica Open Gateway - Production
- url: https://sandbox.opengateway.telefonica.com/v1
  description: Telefónica Open Gateway - Sandbox
tags:
- name: KYC Match
paths:
  /kyc-match:
    post:
      operationId: matchKyc
      summary: Match KYC Data
      description: Validates provided identity data against mobile carrier records. Returns match results for each provided field without exposing the actual stored data. Supports partial matching for flexible verification.
      tags:
      - KYC Match
      security:
      - openIdConnect:
        - kyc-match:match
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KycMatchRequest'
      responses:
        '200':
          description: KYC match results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycMatchResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '422':
          description: Unable to process match request.
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
        code:
          type: string
        message:
          type: string
    KycMatchResponse:
      type: object
      properties:
        phoneNumberMatch:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_available
        idDocumentMatch:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_available
        nameMatch:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_available
        givenNameMatch:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_available
        familyNameMatch:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_available
        addressMatch:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_available
        birthdateMatch:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_available
        emailMatch:
          type: string
          enum:
          - 'true'
          - 'false'
          - not_available
    KycMatchRequest:
      type: object
      properties:
        phoneNumber:
          type: string
          description: Phone number of the user to verify in E.164 format.
          pattern: ^\+[1-9][0-9]{4,14}$
        idDocument:
          type: string
          description: Government ID document number.
        name:
          type: string
          description: Full name to verify.
        givenName:
          type: string
          description: First/given name to verify.
        familyName:
          type: string
          description: Last/family name to verify.
        nameKanaHankaku:
          type: string
          description: Name in half-width katakana (for Japanese carriers).
        nameKanaZenkaku:
          type: string
          description: Name in full-width katakana.
        middleNames:
          type: string
          description: Middle names to verify.
        familyNameAtBirth:
          type: string
          description: Family name at birth (maiden name).
        address:
          type: string
          description: Full address string to verify.
        streetName:
          type: string
        streetNumber:
          type: string
        postalCode:
          type: string
        region:
          type: string
          description: State/region to verify.
        locality:
          type: string
          description: City/locality to verify.
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        houseNumberExtension:
          type: string
        birthdate:
          type: string
          format: date
          description: Date of birth in YYYY-MM-DD format.
        email:
          type: string
          format: email
          description: Email address to verify.
        gender:
          type: string
          enum:
          - MALE
          - FEMALE
          - OTHER
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://opengateway.telefonica.com/.well-known/openid-configuration