Dotfile eKYC check API

openapi: 3.2.0
info:
  title: ⚙️ API specifications eKYC check API
  description: Dotfile public API documentation
  version: v1
  contact: {}
servers:
- url: https://api.dotfile.com
  description: Production environment
security:
- DotfileAPIKey: []
tags:
- name: eKYC check
paths:
  /v1/checks/ekyc:
    post:
      operationId: ekyc-create-one
      summary: Create an eKYC check
      description: Create an eKYC check. The check will verify the identity of the individual using electronic Know Your Customer (eKYC) data sources.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EkycCheckCreate'
            examples:
              withoutSettings:
                summary: Create an eKYC check
                description: Using the body parameter `EkycCheckCreate`
                value:
                  individual_id: 4b36ce30-3d90-421a-b2d9-a046e5e4cfef
              withSettings:
                summary: Create an eKYC check with settings
                description: Using the body parameter `EkycCheckCreate`
                value:
                  individual_id: 4b36ce30-3d90-421a-b2d9-a046e5e4cfef
                  settings:
                    vendor: gbg
                    automatic_approval: true
                    automatic_rejection: true
      responses:
        '201':
          description: 'eKYC check has been created


            **ℹ️ Click to see full payload**'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EkycCheck'
        '400':
          description: "The request is either malformed or contain invalid parameters.\n\n  - Make sure the body payload matches the expected schema\n  - Limit reached. Contact us at support@dotfile.com to lift all limits.\n  "
      tags:
      - eKYC check
  /v1/checks/ekyc/{id}:
    get:
      operationId: ekyc-get-one
      summary: Retrieve an eKYC check
      description: Returns detailed information about the specified eKYC check.
      parameters:
      - name: id
        required: true
        in: path
        description: Id of the eKYC check
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: '**ℹ️ Click to see full payload**'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EkycCheck'
        '400':
          description: "The request is either malformed or contain invalid parameters.\n\n  - Make sure the identifier specified in the URL is a valid UUID\n  "
        '404':
          description: No eKYC check can be found.
      tags:
      - eKYC check
  /v1/checks/ekyc/{id}/review:
    patch:
      operationId: ekyc-review
      summary: Review an eKYC check
      description: Approve or reject an eKYC check. The Reviewer type will be set to `api`.
      parameters:
      - name: id
        required: true
        in: path
        description: Id of the eKYC check
        schema:
          format: uuid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewCheckInput'
      responses:
        '200':
          description: 'eKYC check has been reviewed


            **ℹ️ Click to see full payload**'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EkycCheck'
        '400':
          description: "The request is either malformed or contain invalid parameters.\n\n  - Make sure the identifier specified in the URL is a valid UUID\n  - Make sure the body payload matches the expected schema\n  "
        '404':
          description: No eKYC check can be found.
      tags:
      - eKYC check
components:
  schemas:
    EkycFraudScoreSignal:
      type: object
      properties:
        score:
          type:
          - number
          - 'null'
        band:
          type:
          - string
          - 'null'
        labels:
          type: array
          items:
            type: string
      required:
      - score
      - band
      - labels
    EkycCheckData:
      type: object
      properties:
        result:
          type:
          - string
          - 'null'
          enum:
          - approved
          - rejected
          - error
        decision:
          type:
          - string
          - 'null'
          enum:
          - match
          - inconclusive
          - inconsistent
        settings:
          $ref: '#/components/schemas/EkycCheckDataSettings'
        vendor:
          $ref: '#/components/schemas/EkycCheckDataVendor'
        review:
          $ref: '#/components/schemas/Review'
        information:
          $ref: '#/components/schemas/EkycCheckDataInformation'
        ai:
          $ref: '#/components/schemas/EkycCheckDataAi'
        fraud_signals:
          allOf:
          - $ref: '#/components/schemas/EkycCheckDataFraudSignals'
      required:
      - result
      - decision
      - settings
      - vendor
      - review
      - information
      - fraud_signals
      - ai
    ReviewCheckInput:
      type: object
      properties:
        action:
          type: string
          enum:
          - approve
          - reject
        comment:
          type:
          - string
          - 'null'
          description: Optional comment for the review.
        override:
          type: boolean
          description: Set to true to change the status of an already reviewed check (in status approved or rejected).
      required:
      - action
    EkycCheckDataSettings:
      type: object
      properties:
        vendor:
          type: string
          enum:
          - gbg
        automatic_approval:
          type: boolean
        automatic_rejection:
          type: boolean
      required:
      - vendor
      - automatic_approval
      - automatic_rejection
    EkycCheckDataVendor:
      type: object
      properties:
        name:
          type: string
          enum:
          - gbg
        profile_id:
          type: string
        profile_name:
          type:
          - string
          - 'null'
        country:
          type: string
          format: alpha-2
          minLength: 2
          maxLength: 2
          description: '[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (eg `FR`)'
        score:
          type:
          - number
          - 'null'
      required:
      - name
      - profile_id
      - profile_name
      - country
      - score
    EkycTrustSignal:
      type: object
      properties:
        score:
          type:
          - number
          - 'null'
        band:
          type:
          - string
          - 'null'
        triggered_rules:
          type: array
          items:
            $ref: '#/components/schemas/EkycTrustRule'
      required:
      - score
      - band
      - triggered_rules
    EkycCheckDataInformation:
      type: object
      properties:
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        birth_date:
          type:
          - string
          - 'null'
        address:
          $ref: '#/components/schemas/Address'
      required:
      - first_name
      - last_name
      - birth_date
      - address
    EkycMobileNetwork:
      type: object
      properties:
        operator:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
      required:
      - operator
      - country
    EkycCheckDataFraudSignals:
      type: object
      properties:
        trust:
          allOf:
          - $ref: '#/components/schemas/EkycTrustSignal'
        fraud_score:
          allOf:
          - $ref: '#/components/schemas/EkycFraudScoreSignal'
        email_verification:
          allOf:
          - $ref: '#/components/schemas/EkycEmailVerificationSignal'
        email_validation:
          allOf:
          - $ref: '#/components/schemas/EkycEmailValidationSignal'
        mobile_validation:
          allOf:
          - $ref: '#/components/schemas/EkycMobileValidationSignal'
      required:
      - trust
      - fraud_score
      - email_verification
      - email_validation
      - mobile_validation
    Address:
      type: object
      properties:
        street_address:
          type:
          - string
          - 'null'
        street_address_2:
          type:
          - string
          - 'null'
        postal_code:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        region:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
          format: alpha-2
          minLength: 2
          maxLength: 2
          description: '[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (eg `FR`)'
      required:
      - street_address
      - street_address_2
      - postal_code
      - city
      - state
      - region
      - country
    EkycCheckDataAi:
      type: object
      properties:
        interpretation:
          type:
          - string
          - 'null'
      required:
      - interpretation
    EkycMobileValidationSignal:
      type: object
      properties:
        number_valid:
          type:
          - boolean
          - 'null'
        line_type:
          type:
          - string
          - 'null'
        current_network:
          allOf:
          - $ref: '#/components/schemas/EkycMobileNetwork'
        original_network:
          allOf:
          - $ref: '#/components/schemas/EkycMobileNetwork'
      required:
      - number_valid
      - line_type
      - current_network
      - original_network
    NestedUser:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
      required:
      - id
      - first_name
      - last_name
      - email
    EkycEmailVerificationSignal:
      type: object
      properties:
        risk_score:
          type:
          - number
          - 'null'
        risk_band:
          type:
          - string
          - 'null'
        risk_level:
          type:
          - string
          - 'null'
        email_first_seen:
          type:
          - string
          - 'null'
        domain_first_seen:
          type:
          - string
          - 'null'
        domain_country:
          type:
          - string
          - 'null'
        mailbox_missing:
          type:
          - boolean
          - 'null'
      required:
      - risk_score
      - risk_band
      - risk_level
      - email_first_seen
      - domain_first_seen
      - domain_country
      - mailbox_missing
    Review:
      type: object
      properties:
        comment:
          type:
          - string
          - 'null'
        reviewed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Date time in format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) (`yyyy-MM-ddTHH:mm:ss.S+X` eg `2023-01-31T13:30:00.000Z`)
        reviewer_type:
          type:
          - string
          - 'null'
          enum:
          - user
          - system
          - api
        user:
          allOf:
          - $ref: '#/components/schemas/NestedUser'
      required:
      - comment
      - reviewed_at
      - reviewer_type
      - user
    EkycCheck:
      type: object
      properties:
        id:
          type: string
          format: uuid
        individual_id:
          type: string
          format: uuid
        is_internal:
          type: boolean
        status:
          type: string
          enum:
          - in_progress
          - need_review
          - processing
          - approved
          - rejected
          - expired
          description: ℹ️ Check status `expired` is deprecated and will be removed Q1'25. It will be replaced with an expired flag.
        type:
          type: string
          default: ekyc
          enum:
          - ekyc
        subtype:
          type:
          - string
          - 'null'
          description: Currently always null for `ekyc` Check
        last_activity_at:
          type: string
          format: date-time
          description: "Latest activity date  \nDate time in format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) (`yyyy-MM-ddTHH:mm:ss.S+X` eg `2023-01-31T13:30:00.000Z`)"
        data:
          $ref: '#/components/schemas/EkycCheckData'
      required:
      - id
      - individual_id
      - is_internal
      - status
      - type
      - subtype
      - last_activity_at
      - data
    EkycEmailValidationSignal:
      type: object
      properties:
        address_valid:
          type:
          - boolean
          - 'null'
        bounce_risk:
          type:
          - string
          - 'null'
      required:
      - address_valid
      - bounce_risk
    EkycCheckCreate:
      type: object
      properties:
        individual_id:
          type: string
          format: uuid
        settings:
          description: Settings are optional and if not set it will use your workspace default settings
          allOf:
          - $ref: '#/components/schemas/EkycCheckSettingsCreate'
      required:
      - individual_id
    EkycTrustRule:
      type: object
      properties:
        code:
          type: string
        description:
          type: string
      required:
      - code
      - description
    EkycCheckSettingsCreate:
      type: object
      properties:
        vendor:
          type: string
          enum:
          - gbg
          description: Vendor to use for eKYC verification. Currently only `gbg` is supported.
        automatic_approval:
          type: boolean
        automatic_rejection:
          type: boolean
  securitySchemes:
    DotfileAPIKey:
      type: apiKey
      in: header
      name: X-DOTFILE-API-KEY
      description: Configure your api key in the Workspace settings
x-uploaded-at: '2026-08-14T14:05:07.336Z'
x-commit-sha: f460fa65a5cc33cf4211bbcee7818f93d5b9e8de