Onfido Reports API

openapi: 3.2.0
info:
  contact:
    name: Onfido
    url: https://public.support.onfido.com
  description: "\nCreate trust at onboarding and beyond with a complete, AI-powered digital\nidentity solution built to help you know your customers online. \nAutomation allows you to acquire new customers and reduce costs while\nmeeting global KYC and AML compliance."
  license:
    name: MIT
  title: Onfido Reports API
  version: v3.6
servers:
- url: https://api.{region}.onfido.com/v3.6
  variables:
    region:
      default: eu
      enum:
      - eu
      - us
      - ca
security:
- Token: []
tags:
- name: Reports
paths:
  /repeat_attempts/{report_id}:
    get:
      description: 'Returns all repeat attempts for a given Document report

        '
      operationId: list_repeat_attempts
      parameters:
      - in: path
        name: report_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/repeat_attempts_list'
          description: Repeat attempts object
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Retrieve repeat attempts
      tags:
      - Reports
  /reports:
    get:
      description: 'All the reports belonging to a particular check can be listed from this endpoint.

        '
      operationId: list_reports
      parameters:
      - in: query
        name: check_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reports_list'
          description: List of Reports
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: List reports
      tags:
      - Reports
  /reports/{report_id}:
    get:
      description: 'A single report can be retrieved using this endpoint with the corresponding unique identifier.

        '
      operationId: find_report
      parameters:
      - in: path
        name: report_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
          description: Report object
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Retrieve report
      tags:
      - Reports
  /reports/{report_id}/resume:
    post:
      description: 'Resumes a single paused report.

        '
      operationId: resume_report
      parameters:
      - in: path
        name: report_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Resume report
      tags:
      - Reports
  /reports/{report_id}/cancel:
    post:
      description: 'Cancels single paused reports.

        '
      operationId: cancel_report
      parameters:
      - in: path
        name: report_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Cancel report
      tags:
      - Reports
components:
  schemas:
    device_intelligence_breakdown_breakdown:
      properties:
        device:
          $ref: '#/components/schemas/device_intelligence_breakdown_breakdown_device'
      type: object
    facial_similarity_video_breakdown_visual_authenticity:
      description: Asserts whether the person in the live video is real (not a spoof) and live.
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/facial_similarity_video_breakdown_visual_authenticity_breakdown'
      readOnly: true
      type: object
    watchlist_standard_properties:
      properties:
        records:
          deprecated: true
          description: Returns any matches including, but not limited to, name and date of birth of match, aliases and associates, and relevant events and sources.
          items:
            type: string
          type: array
      type: object
    watchlist_enhanced_properties_records_inner:
      properties:
        address:
          description: All addresses on file.
          items:
            $ref: '#/components/schemas/watchlist_enhanced_properties_records_inner_address_inner'
          type: array
        alias:
          description: Any names that the person is also known as.
          items:
            $ref: '#/components/schemas/watchlist_enhanced_properties_records_inner_alias_inner'
          type: array
        associate:
          description: Any linked persons, for example family relatives or business partners.
          items:
            $ref: '#/components/schemas/watchlist_enhanced_properties_records_inner_associate_inner'
          type: array
        attribute:
          description: Information about the person, for example hair color or nationality.
          items:
            $ref: '#/components/schemas/watchlist_enhanced_properties_records_inner_attribute_inner'
          type: array
        date_of_birth:
          description: All the date of births on file.
          items:
            type: string
          type: array
        event:
          description: Information about events that have occurred to the person, for example deportation or arrest.
          items:
            $ref: '#/components/schemas/watchlist_enhanced_properties_records_inner_event_inner'
          type: array
        full_name:
          description: The name on file
          type: string
        position:
          description: The role, country and date of each position.
          items:
            type: string
          type: array
        source:
          description: Details about where the information was obtained.
          items:
            $ref: '#/components/schemas/watchlist_enhanced_properties_records_inner_source_inner'
          type: array
      type: object
    facial_similarity_video_breakdown_visual_authenticity_breakdown:
      properties:
        liveness_detected:
          $ref: '#/components/schemas/facial_similarity_video_breakdown_visual_authenticity_breakdown_liveness_detected'
        spoofing_detection:
          $ref: '#/components/schemas/facial_similarity_video_breakdown_visual_authenticity_breakdown_spoofing_detection'
      type: object
    device_intelligence_breakdown_breakdown_device:
      description: Asserts whether the device used to upload the media is trustworthy, i.e. it is a real, physical device.
      properties:
        breakdown:
          $ref: '#/components/schemas/device_intelligence_breakdown_breakdown_device_breakdown'
      type: object
    us_driving_licence_breakdown_document:
      description: Asserts whether the document data provided matches a real driving license in the DMV driver's license database.
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/us_driving_licence_breakdown_document_breakdown'
      type: object
    watchlist_aml_breakdown_politically_exposed_person:
      description: Asserts if there are any records found in the proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.
      properties:
        result:
          type: string
      type: object
    document_report:
      allOf:
      - $ref: '#/components/schemas/report_shared'
      - properties:
          breakdown:
            $ref: '#/components/schemas/document_breakdown'
          properties:
            $ref: '#/components/schemas/document_properties'
        type: object
      example:
        result: clear
        documents:
        - id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        breakdown:
          visual_authenticity:
            result: result
            breakdown:
              template:
                result: result
                properties: '{}'
              other:
                result: result
                properties: '{}'
              fonts:
                result: result
                properties: '{}'
              digital_tampering:
                result: result
                properties: '{}'
              picture_face_integrity:
                result: result
                properties: '{}'
              face_detection:
                result: result
                properties: '{}'
              original_document_present:
                result: result
                properties:
                  scan: scan
                  document_on_printed_paper: document_on_printed_paper
                  screenshot: screenshot
                  photo_of_screen: photo_of_screen
              security_features:
                result: result
                properties: '{}'
          compromised_document:
            result: result
            breakdown:
              document_database:
                result: result
                properties: '{}'
              repeat_attempts:
                result: result
                properties: '{}'
          age_validation:
            result: result
            breakdown:
              minimum_accepted_age:
                result: result
                properties: '{}'
          issuing_authority:
            result: result
            breakdown:
              nfc_active_authentication:
                result: result
                properties: '{}'
              nfc_passive_authentication:
                result: result
                properties: '{}'
          data_consistency:
            result: result
            breakdown:
              document_numbers:
                result: result
                properties: '{}'
              gender:
                result: result
                properties: '{}'
              nationality:
                result: result
                properties: '{}'
              date_of_expiry:
                result: result
                properties: '{}'
              issuing_country:
                result: result
                properties: '{}'
              date_of_birth:
                result: result
                properties: '{}'
              last_name:
                result: result
                properties: '{}'
              multiple_data_sources_present:
                result: result
                properties: '{}'
              first_name:
                result: result
                properties: '{}'
              document_type:
                result: result
                properties: '{}'
          data_comparison:
            result: result
            breakdown:
              document_numbers:
                result: result
                properties: '{}'
              gender:
                result: result
                properties: '{}'
              issuing_country:
                result: result
                properties: '{}'
              date_of_expiry:
                result: result
                properties: '{}'
              date_of_birth:
                result: result
                properties: '{}'
              last_name:
                result: result
                properties: '{}'
              first_name:
                result: result
                properties: '{}'
              document_type:
                result: result
                properties: '{}'
          police_record:
            result: result
          data_validation:
            result: result
            breakdown:
              document_numbers:
                result: result
                properties: '{}'
              gender:
                result: result
                properties: '{}'
              mrz:
                result: result
                properties: '{}'
              document_expiration:
                result: result
                properties: '{}'
              date_of_birth:
                result: result
                properties: '{}'
              expiry_date:
                result: result
                properties: '{}'
              barcode:
                result: result
                properties: '{}'
          image_integrity:
            result: result
            breakdown:
              colour_picture:
                result: result
                properties: '{}'
              supported_document:
                result: result
                properties: '{}'
              conclusive_document_quality:
                result: result
                properties:
                  missing_back: missing_back
                  punctured_document: punctured_document
                  watermarks_digital_text_overlay: watermarks_digital_text_overlay
                  digital_document: digital_document
                  corner_removed: corner_removed
                  obscured_data_points: obscured_data_points
                  abnormal_document_features: abnormal_document_features
                  obscured_security_features: obscured_security_features
              image_quality:
                result: result
                properties:
                  incorrect_side: incorrect_side
                  glare_on_photo: glare_on_photo
                  other_photo_issue: other_photo_issue
                  cut_off_document: cut_off_document
                  covered_photo: covered_photo
                  two_documents_uploaded: two_documents_uploaded
                  blurred_photo: blurred_photo
                  no_document_in_image: no_document_in_image
                  damaged_document: damaged_document
                  dark_photo: dark_photo
        name: document
        created_at: '2000-01-23T04:56:07.000Z'
        sub_result: clear
        check_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        href: href
        properties:
          gender: gender
          security_document_number: security_document_number
          date_of_birth: '2000-01-23T00:00:00.000Z'
          security_tier: tier_1
          mother_name: mother_name
          version_number: version_number
          categorisation: categorisation
          widow_name: widow_name
          extracted_data:
            document_number: document_number
            gender: gender
            date_of_birth: '2000-01-23T00:00:00.000Z'
            last_name: last_name
            middle_name: middle_name
            alias_name: alias_name
            widow_name: widow_name
            spouse_name: spouse_name
            mrz_line1: mrz_line1
            full_name: full_name
            mrz_line3: mrz_line3
            nationality: nationality
            date_of_expiry: '2000-01-23T00:00:00.000Z'
            mrz_line2: mrz_line2
            issuing_authority: issuing_authority
            address_line_1: address_line_1
            address_line_3: address_line_3
            address_line_2: address_line_2
            address_line_5: address_line_5
            first_name: first_name
            address_line_4: address_line_4
          mrz_line1: mrz_line1
          spouse_name: spouse_name
          has_issuance_confirmation: 'true'
          real_id_compliance: true
          address_lines:
            street_address: street_address
            country: country
            country_code: country_code
            city: city
            state: state
            postal_code: postal_code
          driving_licence_information:
            codes: codes
            obtainment_date: '2000-01-23T00:00:00.000Z'
            expiry_date: '2000-01-23T00:00:00.000Z'
            category: category
          mrz_line3: mrz_line3
          issuing_country: issuing_country
          mrz_line2: mrz_line2
          tax_number: tax_number
          issuing_state: issuing_state
          first_name: first_name
          barcode:
          - document_number: document_number
            issuing_date: '2000-01-23T00:00:00.000Z'
            gender: gender
            date_of_birth: '2000-01-23T00:00:00.000Z'
            last_name: last_name
            middle_name: middle_name
            real_id_classification: real_id_classification
            date_of_expiry: '2000-01-23T00:00:00.000Z'
            issuing_country: issuing_country
            address_line_1: address_line_1
            address_line_3: address_line_3
            address_line_2: address_line_2
            issuing_state: issuing_state
            address_line_5: address_line_5
            first_name: first_name
            address_line_4: address_line_4
            class: class
            document_type: document_type
          - document_number: document_number
            issuing_date: '2000-01-23T00:00:00.000Z'
            gender: gender
            date_of_birth: '2000-01-23T00:00:00.000Z'
            last_name: last_name
            middle_name: middle_name
            real_id_classification: real_id_classification
            date_of_expiry: '2000-01-23T00:00:00.000Z'
            issuing_country: issuing_country
            address_line_1: address_line_1
            address_line_3: address_line_3
            address_line_2: address_line_2
            issuing_state: issuing_state
            address_line_5: address_line_5
            first_name: first_name
            address_line_4: address_line_4
            class: class
            document_type: document_type
          document_type: document_type
          profession: profession
          nist_identity_evidence_strength: superior
          document_numbers:
          - type: type
            value: value
          - type: type
            value: value
          address: address
          issuing_date: '2000-01-23T00:00:00.000Z'
          document_subtype: document_subtype
          type_of_permit: type_of_permit
          last_name: last_name
          nfc:
            document_number: document_number
            address: address
            gender: gender
            issuing_date: '2000-01-23T00:00:00.000Z'
            date_of_birth: '2000-01-23T00:00:00.000Z'
            place_of_birth: place_of_birth
            full_name: full_name
            nationality: nationality
            issuing_country: issuing_country
            date_of_expiry: '2000-01-23T00:00:00.000Z'
            issuing_authority: issuing_authority
            personal_number: personal_number
            document_type: document_type
          document_classification:
            issuing_country: issuing_country
            issuing_state: issuing_state
            document_type: document_type
          middle_name: middle_name
          alias_name: alias_name
          expatriation: expatriation
          religion: religion
          place_of_birth: place_of_birth
          nationality: nationality
          date_of_expiry: '2000-01-23T00:00:00.000Z'
          father_name: father_name
          issuing_authority: issuing_authority
          civil_state: civil_state
          personal_number: personal_number
          remarks: remarks
        status: awaiting_data
    facial_similarity_motion_breakdown_face_comparison:
      description: Asserts whether the face in the document matches the face in the motion capture.
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/facial_similarity_photo_breakdown_face_comparison_breakdown'
      readOnly: true
      type: object
    document_CDQ_reasons:
      example:
        missing_back: missing_back
        punctured_document: punctured_document
        watermarks_digital_text_overlay: watermarks_digital_text_overlay
        digital_document: digital_document
        corner_removed: corner_removed
        obscured_data_points: obscured_data_points
        abnormal_document_features: abnormal_document_features
        obscured_security_features: obscured_security_features
      properties:
        obscured_data_points:
          description: When data points are obscured to the point that we cannot confirm if the fonts match the expected ones.
          type: string
        obscured_security_features:
          description: When a critical security feature is obscured. This can also refer to when the holder's wet signature, necessary for the document to be valid, is not present.
          type: string
        abnormal_document_features:
          description: One of 3 reasons (1) OCR Assisted Scans (i.e. when you're able to move the mouse and highlight part of text), (2) Severely Washed out Background, (3) Overlapping Text.
          type: string
        watermarks_digital_text_overlay:
          description: Any digital text or electronic watermarks on the document.
          type: string
        corner_removed:
          description: If the corner has been physically cut off. This can be found on some documents that are no longer valid.
          type: string
        punctured_document:
          description: A punched hole is present.
          type: string
        missing_back:
          description: When the back of a document is needed for processing, but is not available.
          type: string
        digital_document:
          description: When a document has been published digitally, there aren't enough security features to review so we cannot perform a full fraud assessment.
          type: string
      type: object
    us_driving_licence_breakdown_personal:
      description: Asserts whether the personal data provided matches a real driving license in the DMV driver's license database.
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/us_driving_licence_breakdown_personal_breakdown'
      type: object
    facial_similarity_report_media:
      properties:
        id:
          description: ID of uploaded biometric media to use.
          format: uuid
          type: string
      required:
      - id
      type: object
    facial_similarity_motion_breakdown_image_integrity:
      description: Asserts whether the quality and integrity of the uploaded files were sufficient to perform a face comparison.
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/facial_similarity_motion_breakdown_image_integrity_breakdown'
      readOnly: true
      type: object
    identity_enhanced_breakdown_address:
      description: Asserts if the applicant's address matches any sources.
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/identity_enhanced_breakdown_address_breakdown'
      type: object
    identity_enhanced_breakdown_sources_breakdown:
      properties:
        total_sources:
          $ref: '#/components/schemas/identity_enhanced_breakdown_sources_breakdown_total_sources'
      type: object
    watchlist_enhanced_report:
      allOf:
      - $ref: '#/components/schemas/report_shared'
      - properties:
          breakdown:
            $ref: '#/components/schemas/watchlist_enhanced_breakdown'
          properties:
            $ref: '#/components/schemas/watchlist_enhanced_properties'
        type: object
    facial_similarity_video_breakdown_image_integrity_breakdown_source_integrity:
      description: Asserts whether the live video is trustworthy - e.g. not from a fake webcam.
      properties:
        result:
          type: string
        properties:
          $ref: '#/components/schemas/video_reasons'
      type: object
    document_video_with_address_information_report:
      allOf:
      - $ref: '#/components/schemas/report_shared'
      - properties:
          breakdown:
            $ref: '#/components/schemas/document_breakdown'
          properties:
            $ref: '#/components/schemas/document_properties'
        type: object
    report_name:
      enum:
      - document
      - document_video
      - document_video_with_address_information
      - document_with_address_information
      - document_with_driving_licence_information
      - document_with_driver_verification
      - facial_similarity_photo
      - facial_similarity_photo_fully_auto
      - facial_similarity_video
      - facial_similarity_motion
      - known_faces
      - identity_enhanced
      - watchlist_aml
      - watchlist_enhanced
      - watchlist_standard
      - watchlist_peps_only
      - watchlist_sanctions_only
      - proof_of_address
      - us_driving_licence
      - device_intelligence
      - india_pan
      type: string
    document_breakdown_age_validation:
      description: Asserts whether the age calculated from the document's date of birth data point is greater than or equal to the minimum accepted age.
      example:
        result: result
        breakdown:
          minimum_accepted_age:
            result: result
            properties: '{}'
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/document_breakdown_age_validation_breakdown'
      type: object
    identity_enhanced_report:
      allOf:
      - $ref: '#/components/schemas/report_shared'
      - properties:
          breakdown:
            $ref: '#/components/schemas/identity_enhanced_breakdown'
          properties:
            $ref: '#/components/schemas/identity_enhanced_properties'
        type: object
    proof_of_address_breakdown_data_comparison:
      description: Asserts whether the first name, last name and address provided by the applicant match those on the PoA document.
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/proof_of_address_breakdown_data_comparison_breakdown'
      type: object
    device_intelligence_breakdown_properties_device:
      properties:
        sdk_version:
          description: The SDK version that was used.
          type: string
        sdk_source:
          description: The SDK used to upload the media.
          enum:
          - onfido-android-sdk
          - onfido-ios-sdk
          - onfido-web-sdk
          type: string
        authentication_type:
          description: The token used to authenticate the request.
          enum:
          - sdk_token
          - mobile_token
          - api_token
          type: string
        raw_model:
          description: The model as set by the phone manufacturer (for Android and iOS) or the browser manufacturer (for Web). The model can be presented in name or number form depending on each manufacturer implementation.
          type: string
        os:
          description: The operating system of the device. The value came from manufacturer implementation (for Android and iOS) or browser's user agent (for Web).
          type: string
        browser:
          description: The browser name reported by the browser's user agent.
          type: string
        emulator:
          description: Whether the device is an emulator.
          type: boolean
        randomized_device:
          description: Whether the device is providing false randomized device and network information.
          type: boolean
        fake_network_request:
          description: Whether device is using stolen security tokens to send the network information.
          type: boolean
        ip_reputation:
          description: Whether there is highly suspicious traffic related to the IP address. The risk depends on the overall ratio of clear checks on a given IP.
          enum:
          - NOT_ENOUGH_DATA
          - HIGH_RISK
          - LOW_RISK
          type: string
        device_fingerprint_reuse:
          description: The number of times the device was used to create a report for a new applicant. A value greater than 1 indicates potential device reuse.
          type: integer
        single_device_used:
          description: Whether the document or biometric media were uploaded from a single device.
          type:
          - boolean
          - 'null'
        document_capture:
          description: Whether the document media were live captured from the device camera.
          enum:
          - live
          - unknown_method
          type: string
        biometric_capture:
          description: Whether the biometric media were live captured from the device camera.
          enum:
          - live
          - unknown_method
          type: string
      type: object
    identity_enhanced_breakdown_mortality:
      description: Asserts if the applicant's details match any death records.
      properties:
        result:
          type: string
      type: object
    facial_similarity_photo_breakdown_visual_authenticity_breakdown_spoofing_detection_properties:
      properties:
        score:
          description: A floating point number between 0 and 1. The closer the score is to 0, the more likely it is to be a spoof.
          format: float
          type: number
      type: object
    document_breakdown_visual_authenticity_breakdown_template:
      description: The document doesn't match the expected template for the document type and country it is from.
      example:
        result: result
        properties: '{}'
      properties:
        result:
          type: string
        properties:
          type: object
      type: object
    facial_similarity_photo_breakdown_image_integrity_breakdown_face_detected:
      description: Asserts a single face of good enough quality has been found in both the document image and the live photo.
      properties:
        result:
          type: string
        properties:
          type: object
      type: object
    us_driving_licence_breakdown_document_breakdown:
      properties:
        category:
          $ref: '#/components/schemas/document_breakdown_data_comparison_breakdown_issuing_country'
        expiration_date:
          $ref: '#/components/schemas/document_breakdown_data_comparison_breakdown_issuing_country'
        issue_date:
          $ref: '#/components/schemas/document_breakdown_data_comparison_breakdown_issuing_country'
        document_number:
          $ref: '#/components/schemas/document_breakdown_data_comparison_breakdown_issuing_country'
      type: object
    facial_similarity_video_breakdown_image_integrity:
      description: Asserts whether the quality and integrity of the uploaded files were sufficient to perform a face comparison.
      properties:
        result:
          type: string
        breakdown:
          $ref: '#/components/schemas/facial_similarity_video_breakdown_image_integrity_breakdown'
      readOnly: true
      type: object
    facial_similarity_photo_breakdown_face_comparison_breakdown:
      properties:
        face_match:
          $ref: '#/components/schemas/facial_similarity_photo_breakdown_face_comparison_breakdown_face_match'
      type: object
    facial_similarity_photo_properties:
      properties:
        score:
          description: 'A floating point number between 0 and 1. The closer the score is to 0, the more likely

            it is to be a spoof (i.e. photos of printed photos, or photos of digital screens).

            Conversely, the closer it is to 1, the less likely it is to be a spoof.

            '
          format: float
          type: number
      type: object
    watchlist_enhanced_properties_records_inner_source_inner:
      properties:
        source_headline:
          type: string
        source_name:
          type: string
        source_url:
          type: string
        source_format:
          type: string
      type: object
    known_faces_properties_matches_inner:
      properties:
        applicant_id:
          description: The applicant ID of the matched applicant.
          format: uuid
          type: string
        score:
          description: A floating point number between 0 and 1 that expresses how similar the two faces are, whe

# --- truncated at 32 KB (157 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/onfido/refs/heads/main/openapi/onfido-reports-api-openapi.yml