openapi: 3.0.1
info:
  title: Shufti Pro Verification API
  description: >-
    Specification of the Shufti Pro identity-verification API. A single REST
    endpoint accepts a verification request containing one or more service
    objects - document, face, address, consent, background_checks, and kyb -
    to run KYC, KYB, and AML compliance across 240+ countries and territories.
    Companion endpoints retrieve verification status and proofs and delete
    verification data. Requests authorize via HTTP Basic Auth (Client ID as
    username, Secret Key as password) or a short-lived Bearer access token.
  termsOfService: https://shuftipro.com/terms-conditions/
  contact:
    name: Shufti Pro Support
    url: https://shuftipro.com/contact-us/
  version: '1.0'
servers:
  - url: https://api.shuftipro.com
paths:
  /:
    post:
      operationId: createVerification
      tags:
        - Verification
      summary: Create a verification request.
      description: >-
        Submits a verification request containing a unique reference, an
        optional callback_url, and one or more service objects (document,
        face, address, consent, background_checks, kyb). In offsite mode with
        show_results set to "0" the request returns request.pending and final
        results are delivered asynchronously to the callback_url.
      security:
        - basicAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
      responses:
        '200':
          description: Verification response.
          headers:
            Signature:
              schema:
                type: string
              description: SHA256 signature of the response body for validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
        '401':
          description: Unauthorised - invalid credentials.
  /status:
    post:
      operationId: getVerificationStatus
      tags:
        - Status
      summary: Get verification status and proofs.
      description: >-
        Retrieves the current status, event, and proof URLs for a previously
        submitted verification by posting its reference.
      security:
        - basicAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
      responses:
        '200':
          description: Status response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
  /delete:
    post:
      operationId: deleteVerification
      tags:
        - Status
      summary: Delete verification data.
      description: >-
        Deletes the stored verification data for a completed request by
        reference. Returns request.deleted on success or request.invalid if
        the reference is unknown or already deleted.
      security:
        - basicAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
      responses:
        '200':
          description: Delete response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Auth using your Client ID as the username and your Secret
        Key as the password.
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer access token shared with the client; valid for 10 minutes and
        single use.
  schemas:
    VerificationRequest:
      type: object
      required:
        - reference
      properties:
        reference:
          type: string
          description: Unique identifier for the verification request.
          example: '17374217'
        callback_url:
          type: string
          format: uri
          description: Server endpoint to receive asynchronous notifications.
        email:
          type: string
          format: email
          description: End-user email address.
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code of the end-user.
          example: US
        language:
          type: string
          description: Language for the verification flow.
        verification_mode:
          type: string
          enum:
            - image_only
            - video_only
            - any
          description: Capture mode for the verification.
        show_results:
          type: string
          enum:
            - '0'
            - '1'
          description: Set to "0" for asynchronous (offsite) responses.
        allow_retry:
          type: string
          enum:
            - '0'
            - '1'
          description: Set to "1" to allow real-time document re-upload.
        ttl:
          type: integer
          description: Time-to-live, in minutes, for an onsite verification link.
        document:
          $ref: '#/components/schemas/DocumentService'
        face:
          $ref: '#/components/schemas/FaceService'
        address:
          $ref: '#/components/schemas/AddressService'
        consent:
          $ref: '#/components/schemas/ConsentService'
        background_checks:
          $ref: '#/components/schemas/BackgroundChecksService'
        kyb:
          $ref: '#/components/schemas/KybService'
    DocumentService:
      type: object
      description: >-
        Document verification supporting 10,000+ document types across 230+
        countries.
      properties:
        proof:
          type: string
          description: Base64-encoded document image (omit to capture onsite).
        supported_types:
          type: array
          items:
            type: string
            enum:
              - id_card
              - passport
              - driving_license
              - credit_or_debit_card
        name:
          $ref: '#/components/schemas/NameObject'
        dob:
          type: string
          format: date
          description: Expected date of birth on the document.
        document_number:
          type: string
        issue_date:
          type: string
          format: date
        expiry_date:
          type: string
          format: date
    FaceService:
      type: object
      description: Facial biometric verification and liveness.
      properties:
        proof:
          type: string
          description: Base64-encoded face image (omit to capture onsite).
    AddressService:
      type: object
      description: Address verification across 240+ territories.
      properties:
        proof:
          type: string
          description: Base64-encoded address proof document.
        full_address:
          type: string
        name:
          $ref: '#/components/schemas/NameObject'
        supported_types:
          type: array
          items:
            type: string
            enum:
              - id_card
              - utility_bill
              - bank_statement
    ConsentService:
      type: object
      description: Handwritten or printed consent verification.
      properties:
        proof:
          type: string
          description: Base64-encoded consent image.
        text:
          type: array
          items:
            type: string
          description: The consent text the user must reproduce.
        supported_types:
          type: array
          items:
            type: string
            enum:
              - handwritten
              - printed
    BackgroundChecksService:
      type: object
      description: >-
        AML background check screening against 1700+ global watchlists,
        sanctions, and PEP lists.
      properties:
        name:
          $ref: '#/components/schemas/NameObject'
        dob:
          type: string
          format: date
          description: End-user date of birth.
        alias_search:
          type: string
          enum:
            - '0'
            - '1'
        filters:
          type: array
          items:
            type: string
            enum:
              - sanction
              - warning
              - fitness-probity
              - pep
              - pep-class-1
              - pep-class-2
              - adverse-media
    KybService:
      type: object
      description: >-
        Know Your Business verification against company registries and
        corporate records.
      properties:
        company_name:
          type: string
        company_jurisdiction_code:
          type: string
          description: Registry jurisdiction code, e.g. us_de.
        company_registration_number:
          type: string
    NameObject:
      type: object
      properties:
        first_name:
          type: string
        middle_name:
          type: string
        last_name:
          type: string
        fuzzy_match:
          type: string
          enum:
            - '0'
            - '1'
    StatusRequest:
      type: object
      required:
        - reference
      properties:
        reference:
          type: string
          description: Reference of the verification to query or delete.
          example: '17374217'
    VerificationResponse:
      type: object
      properties:
        reference:
          type: string
          example: '17374217'
        event:
          type: string
          description: Current verification event.
          enum:
            - request.received
            - request.pending
            - request.invalid
            - request.timeout
            - request.unauthorized
            - request.deleted
            - verification.accepted
            - verification.declined
            - verification.cancelled
            - verification.status.changed
        email:
          type: string
        country:
          type: string
        verification_url:
          type: string
          format: uri
          description: Onsite verification URL, when applicable.
        verification_result:
          type: object
          additionalProperties: true
          description: Per-service pass/fail result map.
        verification_data:
          type: object
          additionalProperties: true
          description: Extracted data per service.
        declined_reason:
          type: string
        declined_codes:
          type: array
          items:
            type: string
    DeleteResponse:
      type: object
      properties:
        reference:
          type: string
          example: '17374217'
        event:
          type: string
          enum:
            - request.deleted
            - request.invalid
          example: request.deleted