Ubble Address document verifications (Coming soon) API

openapi: 3.2.0
info:
  title: Checkout.com - Identity Verification Address document…
  version: 1.0.0
  x-logo:
    url: https://raw.githubusercontent.com/ubbleai/docs/main/cko_doc_logo.png
  description: ''
servers:
- url: https://api.ubble.ai
tags:
- name: Address document verifications (Coming soon)
paths:
  /v2/address-document-verifications:
    post:
      tags:
      - Address document verifications (Coming soon)
      summary: Create an Address Document Verification
      operationId: create_address_document_verification
      description: Creates an Address Document Verification
      requestBody:
        required: true
        content:
          application/json:
            examples:
              address_document_verification_creation_request_body_min:
                $ref: '#/components/examples/address_document_verification_creation_request_body_min'
              address_document_verification_creation_request_body_max:
                $ref: '#/components/examples/address_document_verification_creation_request_body_max'
            schema:
              $ref: '#/components/schemas/AddressDocumentVerificationInputPost'
      responses:
        '201':
          description: Address Document Verification created successfully
          content:
            application/json:
              examples:
                address_document_verification_creation_response_body:
                  $ref: '#/components/examples/address_document_verification_creation_response_body'
              schema:
                allOf:
                - $ref: '#/components/schemas/AddressDocumentVerificationOutputPost'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
        '500':
          description: Internal server error
        '503':
          description: Service unavailable
  /v2/address-document-verifications/{address_document_verification_id}:
    get:
      tags:
      - Address document verifications (Coming soon)
      summary: Retrieve an Address Document Verification
      description: This endpoint allows you to get the detailed results of an Address Document Verification
      operationId: retrieve_address_document_verification
      parameters:
      - name: address_document_verification_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/AddressDocumentVerificationId'
      responses:
        '200':
          description: Address Document Verification retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/AddressDocumentVerificationOutputGet'
        '404':
          description: Address Document Verification not found
        '500':
          description: Internal server error
  /v2/address-document-verifications/{address_document_verification_id}/anonymize:
    post:
      tags:
      - Address document verifications (Coming soon)
      summary: Anonymize an Address Document Verification
      operationId: anonymize_address_document_verification
      description: Anonymize the personal data of an Address Document Verification with the specified ID.
      parameters:
      - name: address_document_verification_id
        in: path
        description: ID of the document verification to anonymize
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Address Document Verification anonymized
          content:
            application/json:
              examples:
                address_document_verification_anonymization_response_body:
                  $ref: '#/components/examples/address_document_verification_anonymization_response_body'
              schema:
                required:
                - applicant_id
                - user_journey_id
                allOf:
                - $ref: '#/components/schemas/AddressDocumentVerificationOutputAnonymize'
        '404':
          description: Address Document Verification not found
        '500':
          description: Internal server error
  /v2/address-document-verifications/{address_document_verification_id}/attempts:
    get:
      tags:
      - Address document verifications (Coming soon)
      summary: List Address Document Verification attempts
      operationId: list_attempts_address_document_verification
      description: 'This endpoint allows you to list all attempts of an Address Document Verification.


        Attempts are returned ordered by creation date, newest first.


        The response is paginated (see Pagination section).

        You can navigate through pages using the `skip` and `limit` query parameters or by following the URLs in the `_links` object.'
      parameters:
      - name: address_document_verification_id
        in: path
        description: ID of the document verification
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/skipParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: Address Document Verification attempts retrieved successfully
          content:
            application/json:
              examples:
                address_document_verification_attempt_list_response_body:
                  $ref: '#/components/examples/address_document_verification_attempt_list_response_body'
              schema:
                allOf:
                - $ref: '#/components/schemas/AddressDocumentVerificationAttemptOutputList'
        '404':
          description: The provided document verification ID is not valid
        '500':
          description: An error occurred while fetching the attempts
    post:
      tags:
      - Address document verifications (Coming soon)
      summary: Create an Address Document Verification attempt
      description: 'This endpoint allows you to create an Address Document Verification attempt. It is possible when the Address Document Verification is one of the following statuses: `created`, `retry_required`'
      operationId: create_address_document_verification_attempt
      parameters:
      - name: address_document_verification_id
        in: path
        description: ID of the document verification
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            examples:
              address_document_verification_attempt_creation_request_body_min:
                $ref: '#/components/examples/address_document_verification_attempt_creation_request_body_min'
              address_document_verification_attempt_creation_request_body_max:
                $ref: '#/components/examples/address_document_verification_attempt_creation_request_body_max'
            schema:
              $ref: '#/components/schemas/AddressDocumentVerificationAttemptInputPost'
      responses:
        '201':
          description: Address Document Verification attempt created
          content:
            application/json:
              examples:
                address_document_verification_attempt_creation_response_body:
                  $ref: '#/components/examples/address_document_verification_attempt_creation_response_body'
              schema:
                $ref: '#/components/schemas/AddressDocumentVerificationAttemptOutputPost'
        '404':
          description: The provided Address Document Verification ID is not valid
        '409':
          description: The Address Document Verification is not in a valid state to create an attempt. The Address Document Verification status must be `created` or `retry_required`
        '500':
          description: An error occurred while creating the attempt
  /v2/address-document-verifications/{address_document_verification_id}/attempts/{attempt_id}:
    get:
      tags:
      - Address document verifications (Coming soon)
      summary: Retrieve an Address Document Verification attempt
      description: This endpoint allows you to retrieve the details for a given Address Document Verification attempt.
      operationId: fetch_attempts_address_document_verification
      parameters:
      - name: address_document_verification_id
        in: path
        description: ID of the document verification
        required: true
        schema:
          type: string
      - name: attempt_id
        in: path
        description: ID of the document verification attempt
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Address Document Verification attempt retrieved successfully
          content:
            application/json:
              examples:
                address_document_verification_attempt_get_response_body:
                  $ref: '#/components/examples/address_document_verification_attempt_get_response_body'
              schema:
                allOf:
                - $ref: '#/components/schemas/AddressDocumentVerificationAttemptOutputGet'
        '404':
          description: The provided document verification attempt ID is not valid
        '500':
          description: An error occurred while fetching the attempt
  /v2/address-document-verifications/{address_document_verification_id}/attempts/{attempt_id}/assets:
    get:
      tags:
      - Address document verifications (Coming soon)
      summary: Retrieve an Address Document Verification attempt asset
      operationId: fetch_asset_address_document_verification_attempt
      description: 'This endpoint allows you to retrieve the assets associated with an Address Document Verification.

        This includes the document image.


        The response is paginated (see Pagination section).

        You can navigate through pages using the `skip` and `limit` query parameters or by following the URLs in the `_links` object.'
      parameters:
      - name: address_document_verification_id
        in: path
        description: ID of the Address Document Verification
        required: true
        schema:
          type: string
      - name: attempt_id
        in: path
        description: ID of the Address Document Verification attempt
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/skipParam'
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: Address Document Verification attempt asset retrieved successfully
          content:
            application/json:
              examples:
                address_document_verification_attempt_output_assets_response_body:
                  $ref: '#/components/examples/address_document_verification_attempt_output_assets_response_body'
              schema:
                $ref: '#/components/schemas/AddressDocumentVerificationAttemptAssetsOutput'
  /v2/address-document-verifications/{address_document_verification_id}/notify:
    post:
      tags:
      - Address document verifications (Coming soon)
      summary: Request webhook notification
      operationId: notify_address_document_verification
      description: This endpoint can be used to initiate a webhook call containing the latest event of an Address Document Verification
      parameters:
      - name: address_document_verification_id
        in: path
        description: ID of the document verification to notify
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_url:
                  type: string
                  format: uri
      responses:
        '204':
          description: Notification successfully requested
  /v2/address-document-verifications/{address_document_verification_id}/pdf-report:
    get:
      tags:
      - Address document verifications (Coming soon)
      summary: Retrieve PDF report of an Address Document Verification
      operationId: pdf_address_document_verification
      description: 'This endpoint allows you to retrieve a PDF report of an Address Document Verification.


        Please note that the PDF report is only available for address document verifications that are

        in status `declined` and `approved` once you receive the `address_document_verification_report_created` event.'
      parameters:
      - name: address_document_verification_id
        in: path
        description: ID of the Address Document Verification
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Address Document Verification PDF report retrieved successfully
          content:
            application/json:
              examples:
                address_document_verification_pdf_report_response_body:
                  $ref: '#/components/examples/address_document_verification_pdf_report_response_body'
              schema:
                $ref: '#/components/schemas/AddressDocumentVerificationOutputPdfReport'
        '404':
          description: The PDF report is not available
components:
  schemas:
    AddressDocumentVerificationAttemptOutputBase:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/AddressDocumentVerificationAttemptStates'
        response_codes:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/ResponseCodes'
        _links:
          $ref: '#/components/schemas/SelfLink'
      allOf:
      - $ref: '#/components/schemas/DatedObject'
    HalLink:
      type: object
      required:
      - href
      properties:
        href:
          type: string
          format: uri
    ListLinks:
      type: object
      required:
      - self
      properties:
        self:
          description: Link to the current page
          $ref: '#/components/schemas/HalLink'
        previous:
          description: Link to the previous page (null if on the first page)
          $ref: '#/components/schemas/HalLink'
        next:
          description: Link to the next page (null if on the last page)
          $ref: '#/components/schemas/HalLink'
    AddressDocumentVerificationStatus:
      type: string
      description: Address Document Verification status.
      enum:
      - created
      - quality_checks_in_progress
      - checks_in_progress
      - approved
      - declined
      - retry_required
      - inconclusive
    AddressDocumentVerificationInputPost:
      type: object
      required:
      - applicant_id
      - user_journey_id
      allOf:
      - $ref: '#/components/schemas/AddressDocumentVerificationInputBase'
    AddressDocumentVerificationAttemptOutputPost:
      type: object
      required:
      - id
      - status
      - response_codes
      - _links
      allOf:
      - $ref: '#/components/schemas/AddressDocumentVerificationAttemptOutputBase'
    AddressDocumentVerificationLinks:
      type: object
      allOf:
      - $ref: '#/components/schemas/SelfLink'
    AddressDocumentVerificationAttemptInputPost:
      type: object
      required:
      - document
      allOf:
      - $ref: '#/components/schemas/AddressDocumentVerificationAttemptInputBase'
    AddressDocumentVerificationInputBase:
      type: object
      allOf:
      - $ref: '#/components/schemas/AddressDocumentVerificationBase'
    BaseOutputList:
      type: object
      properties:
        total_count:
          type: integer
          description: Total number of items available across all pages
        skip:
          type: integer
          description: Number of items skipped (offset from the start)
        limit:
          type: integer
          description: Maximum number of items returned in this page
        _links:
          $ref: '#/components/schemas/ListLinks'
    DatedObject:
      type: object
      required:
      - created_on
      - modified_on
      properties:
        created_on:
          description: UTC Date time when the resource was created
          type: string
          format: date-time
          example: 2017-07-21 17:32:28+00:00
        modified_on:
          description: UTC Date time when the resource was modified
          type: string
          format: date-time
          example: 2017-07-21 17:40:32+00:00
    AddressDocumentVerificationAttemptStates:
      type: string
      description: Address Document Verification attempt state.
      enum:
      - quality_checks_in_progress
      - checks_in_progress
      - completed
      - quality_checks_aborted
      - checks_inconclusive
      - terminated
    AddressDocumentVerificationBase:
      type: object
      properties:
        user_journey_id:
          allOf:
          - $ref: '#/components/schemas/UserJourneyId'
        applicant_id:
          allOf:
          - $ref: '#/components/schemas/ApplicantId'
        webhook_url:
          type: string
          format: uri
        declared_data:
          $ref: '#/components/schemas/DeclaredData'
    CountryCodeIso2:
      type: string
      format: ISO 3166-1 alpha-2
      pattern: ^[A-Za-z]{2}$
      example: US
    ProofOfAddressDocument:
      type: object
      properties:
        document_type:
          type: string
        issuer:
          type: string
        full_names:
          type: array
          items:
            type: string
        address:
          $ref: '#/components/schemas/Address'
        issue_date:
          type: string
          format: date
    AddressDocumentVerificationOutputPdfReport:
      type: object
      required:
      - pdf_report
      properties:
        pdf_report:
          type: string
          format: uri
    AddressDocumentVerificationAttemptInputBase:
      type: object
      properties:
        document:
          type: string
          format: binary
    AddressDocumentVerificationAttemptAssetsOutput:
      type: object
      required:
      - total_count
      - skip
      - limit
      - _links
      - data
      properties:
        data:
          type: array
          description: Array of Address Document Verification attempt assets for the current page
          minItems: 0
          items:
            $ref: '#/components/schemas/AddressDocumentVerificationAttemptAsset'
      allOf:
      - $ref: '#/components/schemas/BaseOutputList'
    AddressDocumentVerificationAttemptOutputList:
      type: object
      required:
      - total_count
      - skip
      - limit
      - _links
      - data
      properties:
        data:
          type: array
          description: Array of Address Document Verification attempts for the current page
          minItems: 0
          items:
            $ref: '#/components/schemas/AddressDocumentVerificationAttemptOutputGet'
      allOf:
      - $ref: '#/components/schemas/BaseOutputList'
    RiskLabel:
      type: string
      description: Risk assessment label.
      enum:
      - multiple_faces_detected
      - mcc_not_confident
      - risky_document_format
    AddressDocumentVerificationAttemptAsset:
      type: object
      required:
      - type
      - _links
      properties:
        type:
          type: string
          description: Type of asset
          enum:
          - document
        _links:
          type: object
          properties:
            asset_url:
              type: object
              properties:
                href:
                  type: string
                  format: uri
    AddressDocumentVerificationAttemptOutputGet:
      type: object
      required:
      - id
      - status
      - response_codes
      - _links
      allOf:
      - $ref: '#/components/schemas/AddressDocumentVerificationAttemptOutputBase'
    Address:
      type: object
      properties:
        address_line1:
          type: string
          maxLength: 250
        address_line2:
          type: string
          maxLength: 250
        city:
          type: string
          maxLength: 50
        state:
          type: string
          maxLength: 50
        zip:
          type: string
          maxLength: 50
        country:
          $ref: '#/components/schemas/CountryCodeIso2'
    AddressDocumentVerificationOutputAnonymize:
      type: object
      required:
      - id
      - status
      - applicant_id
      - user_journey_id
      - response_codes
      - _links
      allOf:
      - $ref: '#/components/schemas/AddressDocumentVerificationOutputBase'
    DeclaredData:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 255
        birth_date:
          type: string
          format: date
    AddressDocumentVerificationOutputPost:
      type: object
      required:
      - id
      - status
      - applicant_id
      - response_codes
      - user_journey_id
      - _links
      allOf:
      - $ref: '#/components/schemas/AddressDocumentVerificationOutputBase'
    AddressDocumentVerificationOutputBase:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AddressDocumentVerificationId'
        status:
          $ref: '#/components/schemas/AddressDocumentVerificationStatus'
        response_codes:
          type: array
          items:
            $ref: '#/components/schemas/ResponseCodes'
        risk_labels:
          $ref: '#/components/schemas/RiskLabels'
        address_document:
          $ref: '#/components/schemas/ProofOfAddressDocument'
        _links:
          $ref: '#/components/schemas/AddressDocumentVerificationLinks'
      allOf:
      - $ref: '#/components/schemas/AddressDocumentVerificationBase'
      - $ref: '#/components/schemas/DatedObject'
    AddressDocumentVerificationOutputGet:
      type: object
      required:
      - id
      - status
      - applicant_id
      - response_codes
      - user_journey_id
      - _links
      allOf:
      - $ref: '#/components/schemas/DatedObject'
      - $ref: '#/components/schemas/AddressDocumentVerificationOutputBase'
    ResponseCodes:
      type: object
      description: The code giving more details about the result.
      properties:
        code:
          $ref: '#/components/schemas/ResponseCode'
        summary:
          $ref: '#/components/schemas/ResponseSummary'
      required:
      - code
      - summary
    ResponseSummary:
      type: string
      description: A descriptive code of the response code.
    ResponseCode:
      type: integer
      description: The numeric code of the response code.
      minimum: 10000
      maximum: 69999
    ApplicantId:
      type: string
      description: Applicant unique identifier.
      pattern: ^aplt_\w+$
      example: aplt_tkoi5db4hryu5cei5vwoabr7we
    AddressDocumentVerificationId:
      type: string
      description: Address Document Verification unique identifier.
      pattern: ^adv_\w+$
      example: adv_tkoi5db4hryu5cei5vwoabr7we
    UserJourneyId:
      type: string
      description: User journey unique identifier.
      pattern: ^usj_\w+$
      example: usj_tkoi5db4hryu5cei5vwoabr7we
    SelfLink:
      type: object
      required:
      - self
      properties:
        self:
          $ref: '#/components/schemas/HalLink'
    RiskLabels:
      type: array
      items:
        $ref: '#/components/schemas/RiskLabel'
      description: Risk assessment labels
  parameters:
    limitParam:
      name: limit
      in: query
      description: Maximum number of items to return per page
      required: false
      schema:
        type: integer
        minimum: 1
        default: 10
    skipParam:
      name: skip
      in: query
      description: Number of items to skip (offset)
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
  examples:
    address_document_verification_attempt_output_assets_response_body:
      value:
        total_count: 1
        skip: 10
        limit: 10
        _links:
          self:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adv_attempt_123/assets
          next:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adv_attempt_123/assets/...
          previous:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adv_attempt_123/assets/...
        data:
        - type: document
          _links:
            asset_url:
              href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adv_attempt_123/assets/document
    address_document_verification_attempt_creation_response_body:
      value:
        id: adv_tkoi5db4hryu5cei5vwoabr7we
        created_on: 2017-07-21 17:32:28+00:00
        modified_on: 2017-07-21 17:40:32+00:00
        status: completed
        response_codes: []
        _links:
          self:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adv_attempt_123
    address_document_verification_attempt_get_response_body:
      value:
        id: adv_tkoi5db4hryu5cei5vwoabr7we
        created_on: 2017-07-21 17:32:28+00:00
        modified_on: 2017-07-21 17:40:32+00:00
        status: completed
        response_codes: []
        _links:
          self:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adv_attempt_123
    address_document_verification_attempt_creation_request_body_min:
      value:
        document: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…

          '
    address_document_verification_creation_request_body_max:
      value:
        user_journey_id: usj_tkoi5db4hryu5cei5vwoabr7we
        applicant_id: aplt_tkoi5db4hryu5cei5vwoabr7we
        declared_data:
          name: Acme Corporation
        webhook_url: https://my.api/events/
    address_document_verification_pdf_report_response_body:
      value:
        pdf_report: https://www.example.com/reports/adv_123.pdf
    address_document_verification_creation_response_body:
      value:
        id: adv_tkoi5db4hryu5cei5vwoabr7we
        created_on: '2017-07-21T17:32:28Z'
        modified_on: '2017-07-21T17:40:32Z'
        user_journey_id: usj_tkoi5db4hryu5cei5vwoabr7we
        applicant_id: aplt_tkoi5db4hryu5cei5vwoabr7we
        status: created
        response_codes: []
        declared_data:
          name: Acme Corporation
        address_document:
          type: Utility Bill
          full_name: Acme Corporation
          address:
            address_line1: 123 Main St
            address_line2: Suite 100
            city: New York
            state: NY
            zip: '10001'
            country: US
          issue_date: 2023-01-15
        webhook_url: https://my.api/events/
        _links:
          self:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we
    address_document_verification_creation_request_body_min:
      value:
        user_journey_id: usj_tkoi5db4hryu5cei5vwoabr7we
        applicant_id: aplt_tkoi5db4hryu5cei5vwoabr7we
        declared_data:
          name: Acme Corporation
    address_document_verification_attempt_list_response_body:
      value:
        total_count: 2
        skip: 10
        limit: 10
        data:
        - id: adv_tkoi5db4hryu5cei5vwoabr7we
          created_on: 2017-07-21 17:32:28+00:00
          modified_on: 2017-07-21 17:40:32+00:00
          status: completed
          response_codes: []
          _links:
            self:
              href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/adv_attempt_123
        _links:
          self:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts
          next:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/...
          previous:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we/attempts/...
    address_document_verification_anonymization_response_body:
      value:
        id: adv_tkoi5db4hryu5cei5vwoabr7we
        created_on: 2017-07-21 17:32:28+00:00
        modified_on: 2017-07-21 17:40:32+00:00
        user_journey_id: usj_tkoi5db4hryu5cei5vwoabr7we
        applicant_id: aplt_tkoi5db4hryu5cei5vwoabr7we
        status: created
        response_codes: []
        webhook_url: https://my.api/events/
        _links:
          self:
            href: https://api.ubble.ai/v2/address-document-verifications/adv_tkoi5db4hryu5cei5vwoabr7we
    address_document_verification_attempt_creation_request_body_max:
      value:
        document: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…

          '
x-tagGroups:
- name: Endpoints documentation
  tags:
  - Applicants
  - Business applicants
  - Identity verifications
  - ID document verifications
  - Face authentications
  - AML verifications
  - Website verifications (Coming soon)
  - Bank document verifications (Coming soon)
  - Company document verifications (Coming soon)
  - Address document verifications (Coming soon)
  - Service status