openapi: 3.2.0
x-stoplight:
  id: 3r5vahhtd02s0
info:
  title: cidaas ID Validator API
  description: |-
    ## ID Validator Services

    The **cidaas ID validator API Documentation** consists of five sections:

    1. **Invocation** to initialize a case and start the identity validation.

    2. **Settings** that allows to setup different identification scenarios and flows.

    3. **Result** of the identification performed.

    4. **Cards** that the ID validator support

    5. **Docs** signed by the user in the identification and signature process

    **Note:** The second section to configure the ID validator can be also done using the **cidaas admin portal**.

    **id validator settings** help you control how an **id validation flow** gets processed.

    The **id validator settings** can be marked as a **template** by setting a **template_name**.

    **Flow type:** A flow type defines **which steps need to be performed during the validation** and thereby **enables ensuring that all requirements are met**, for instance,
    1. Perform eIDAS compliant autoident
    2. Perform eIDAS autoident and sign agreements with qualified signature
    3. Perform a card scan only
    4. Perform autoident based on an id card e.g. driving license, passport etc

    **Allowed cards** define which **identity documents** and even more specifically which **versions of the identity documents** are allowed to be used for **end-user verification**.

    The **invocation of id validator** initializes the **id verification** for the user who has been already created using an **accessToken** containing a **sub (unique identifier of the user)** for configured **id validation settings**. It  initializes the **identification flow** based on applied **id validation settings** by redirecting to the **id validator user interface**.

    The section, **result** helps **retrieve the case result** for a particular **case id**.
  version: 1.3.0
  contact:
    name: cidaas support
    url: 'https://support.cidaas.com'
    email: support@cidaas.de
  summary: 'cidaas ID Validator API for qualified identification of a person and its documents like passport, id card, ...'
  termsOfService: 'https://www.cidaas.com/terms-of-use/'
  license:
    url: 'https://www.cidaas.com/terms-of-use/'
    name: Subscription
servers:
  - url: 'https://domain'
    description: Enter your domain name
  - url: 'https://demo.cidaas.de'
    description: Demo environment
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: 'https://domain/.well-known/openid-configuration'
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://domain/token-srv/token'
          scopes:
            'cidaas:idval_process_start': Start a new ID validation process.
            'cidaas:idval_process_read': Retrieve status information about an ID validation process.
            'cidaas:idval_result_read': Retrieve detailed results of completed ID validation cases.
            'cidaas:idval_media_read': Access media files associated with ID validation cases.
            'cidaas:webhook_manage': Register and manage webhook endpoints for ID validation events.
            'cidaas:idval_settings_read': Read ID validation settings configurations.
            'cidaas:idval_settings_write': Create and update ID validation settings.
            'cidaas:idval_settings_delete': Delete ID validation settings.
  requestBodies:
    Start-Process:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StartProcess'
  schemas:
    StartProcess:
      title: Start Process
      x-stoplight:
        id: 94qcr5q81zvlc
      type: object
      required:
        - validation_settings_id
        - redirect_url
        - user_id_type
        - unique_user_id
      properties:
        validation_settings_id:
          type: string
          x-stoplight:
            id: ix3j7c7tmaqek
          format: uuid
          description: UUID of the ID validation configuration.
          example: 9838425c-4f8d-4d7b-b758-59e80dab0813
        redirect_url:
          type: string
          x-stoplight:
            id: jvbf5cfht18ol
          description: URL to which the user will be redirected to after completing the ID validation.
          example: 'https://example.com/age-verification'
        user_id_type:
          x-stoplight:
            id: ewiz97m6jhqgw
          enum:
            - sub
            - email
            - phone
          description: Type of the unique user ID.
        unique_user_id:
          type: string
          x-stoplight:
            id: k6r7eb2w6604m
          description: Unique identifier of the user.
          example: example@mail.com
        external_reference:
          type: string
          x-stoplight:
            id: ynvpgcwt8zhe9
          description: 'Optional reference, for you to re-identify the ID validation.'
          example: idval-456873
        consents:
          $ref: '#/components/schemas/Consents'
          x-stoplight:
            id: 0jxu0hdrr2v7z
          description: Consents which have already been granted by the user in your system. **Required** if the consent configuration is disabled in the used ID validation configuration.
        custom_attributes:
          type: object
          x-stoplight:
            id: bytbodpd63wyr
          description: 'Key-Value object, which holds the "ground truth" for the tasks _Prevalidation_ and _Document Data Matching_. Mandatory if one of these configurations is enabled in the ID validation configuration.'
    Consents:
      title: Consents
      x-stoplight:
        id: j7dsggnlh4hw6
      type: array
      minItems: 1
      description: Array containing all consents
      items:
        $ref: '#/components/schemas/Consent'
        x-stoplight:
          id: 4d5ul3np6l93n
    Consent:
      title: Consent
      x-stoplight:
        id: zr7k1tuz09tg3
      type: object
      description: Holds all information regarding a consent which was already granted or will be granted during the ID validation.
      required:
        - name
        - url
      properties:
        name:
          type: string
          x-stoplight:
            id: 0d1d9jy3f7u68
          example: processing-consent
          description: Descriptive name of the consent
        url:
          type: string
          x-stoplight:
            id: n2msrlfn76s7c
          format: uri
          description: Publicly available URL
          example: 'https://example.com/consents/age-verification'
    ErrorResponse:
      title: Error Response
      x-stoplight:
        id: shst31q4r01ib
      type: object
      properties:
        success:
          type: boolean
          x-stoplight:
            id: oq8irmvk2k5pv
          description: Indicates the success of the operation.
        status:
          type: integer
          x-stoplight:
            id: bij6aepicnawt
          minimum: 100
          maximum: 599
          example: 404
          description: HTTP status code.
        error:
          type: string
          x-stoplight:
            id: y83brktgvfd7p
          description: Human readable error message.
          example: Process not found
        code:
          type: string
          x-stoplight:
            id: 4fe1oh9617sho
          description: Non human readable error code. Mainly used for troubleshooting and easier debugging of issues.
          example: IVC-0011
    ProcessStatus:
      type: object
      x-examples:
        Example 1:
          processId: f5105102-9003-4a41-b1f3-930714ba7897
          caseId: b2a99592-f854-4f34-b488-9fa73e8aaaba
          executionStatus: paused
          user_task_url: 'https://myapp-example.cidaas.de/id-validator-webapp/processes/f5105102-9003-4a41-b1f3-930714ba7897/tasks/consent'
          user_redirect_url: 'https://myapp-example.cidaas.de'
          browser_redirect: false
      properties:
        processId:
          type: string
          description: UUID of the ID validation process.
          example: f5105102-9003-4a41-b1f3-930714ba7897
        caseId:
          type: string
          description: UUID of the ID validation case
          example: b2a99592-f854-4f34-b488-9fa73e8aaaba
        executionStatus:
          type: string
          description: Execution status of the current task.
          example: paused
        user_task_url:
          type: string
          description: URL on which the user can continue the current ID validation task.
          format: uri
          example: 'https://demo.cidaas.de/id-validator-webapp/processes/f5105102-9003-4a41-b1f3-930714ba7897/tasks/consent'
        user_redirect_url:
          type: string
          format: uri
          example: 'https://example.com/age-verification'
          description: URL to which the user will be redirected to after completing the ID validation.
        browser_redirect:
          type: boolean
          description: Indicates whether the response acts as a redirect.
      title: Process Status
    Validation-Result:
      title: Validation Result
      x-stoplight:
        id: hs79tobkslela
      type: object
      required:
        - _id
        - processId
        - status
        - execution_parameter
        - createdTime
        - updatedTime
      properties:
        _id:
          type: string
          x-stoplight:
            id: pafpk7v0eo7em
          format: uuid
          description: UUID of the ID validation.
          example: 23ece0c0-4d8a-4add-afd7-4b7df9abae24
        processId:
          type: string
          x-stoplight:
            id: minol5hmn2hjr
          format: uuid
          description: UUID of the ID validation process.
          example: 2d4e98fd-ac75-4085-96c6-1bdfc617a76e
        status:
          type: string
          x-stoplight:
            id: y3cn1m1r50lcy
          enum:
            - OPEN
            - FINISHED
          description: Status of the ID validation case.
        execution_parameter:
          $ref: '#/components/schemas/Execution-Parameter'
          x-stoplight:
            id: v1g4ynwat8m9p
        result:
          $ref: '#/components/schemas/Case-Result'
          x-stoplight:
            id: nu57s1jok7fuj
        createdTime:
          type: string
          x-stoplight:
            id: eacpnqlsp0bvc
          example: '2025-11-20T10:30:56.637Z'
          description: Creation Date of ID Validation (ISO 8601)
        updatedTime:
          type: string
          x-stoplight:
            id: fxhmpd1u1lzhl
          description: Latest Update Date of ID Validation (ISO 8601)
          example: '2025-11-20T10:35:16.765Z'
    Execution-Parameter:
      title: Execution Parameter
      x-stoplight:
        id: xymsd0u2v9adp
      type: object
      description: Execution Parameters of an ID validation
      required:
        - validation_settings_id
        - unique_user_id
        - user_id_type
        - mode
        - redirect_uri
        - tenantKey
        - taskConfiguration
      properties:
        validation_settings_id:
          type: string
          x-stoplight:
            id: sdz6s3b7zinw6
          format: uuid
          example: 23ece0c0-4d8a-4add-afd7-4b7df9abae24
        unique_user_id:
          type: string
          x-stoplight:
            id: 5b3r2sdcfvg0r
          example: hans.hansemann@mail.com
        user_id_type:
          type: string
          x-stoplight:
            id: ii3gsuibtdcoc
          example: email
        mode:
          type: string
          x-stoplight:
            id: f9szymqtkowbz
          enum:
            - IdentCard
            - IdentPhoto
            - IdentLight
            - IdentEidas
            - AgeCheckCard
            - AgeCheckLight
            - AgeCheckEssential
            - OnboardingLight
            - OnboardingEssential
          description: The validation mode/flow type that defines which steps need to be performed during the validation.
        external_reference:
          type: string
          x-stoplight:
            id: bwwz83ayj1q39
          example: idval-156189
        redirect_uri:
          type: string
          x-stoplight:
            id: za7nk2y91txx3
          format: uri
          example: 'https://www.example.com/age-verification'
        tenantKey:
          type: string
          x-stoplight:
            id: zo3hs32bmtlki
          example: cidaas-exampleTenant-prod
        taskConfiguration:
          $ref: '#/components/schemas/Task-Configuration'
          x-stoplight:
            id: pnh60s4g3pw1w
          description: Holds all task configurations for this ID validation.
    Task-Configuration:
      title: Task Configuration
      x-stoplight:
        id: r6laa00ijn5d9
      type: object
      required:
        - prevalidation_config
        - document_data_matching_config
        - consent_config
      properties:
        prevalidation_config:
          $ref: '#/components/schemas/Prevalidation-Config'
          x-stoplight:
            id: u6qz5v1xhwetd
          description: '`Prevalidation` configuration for this ID validation'
        document_data_matching_config:
          $ref: '#/components/schemas/Document-Data-Matching-Config'
          x-stoplight:
            id: y7f1xc4soaj51
          description: '`Document Data Matching` configuration for this ID validation'
        consent_config:
          $ref: '#/components/schemas/Consent-Config'
          x-stoplight:
            id: awj9ja20ljr42
          description: '`Consent` configuration for this ID validation'
        custom_attributes:
          type: object
          x-stoplight:
            id: gdd861vjoe5j9
          description: Key-Value pairs of "ground truth" data.
    Prevalidation-Config:
      title: Prevalidation Configuration
      x-stoplight:
        id: 6bbnn2r958dfw
      type: object
      required:
        - enabled
        - fields
        - description
      properties:
        enabled:
          type: boolean
          x-stoplight:
            id: tr3lcu7aem4bu
          description: Whether the task `Prevalidation` is enabled.
        fields:
          type: array
          x-stoplight:
            id: l1p7hi3evytey
          description: Array of validation fields.
          items:
            $ref: '#/components/schemas/Validation-Field'
            x-stoplight:
              id: awmvrhoytvvq9
        description:
          type: object
          x-stoplight:
            id: m72eo4l1zh7qe
          description: Localization map where the `key` is the country code (e.g. `en`) and the value the human readable description text shown during the prevalidation task.
          additionalProperties:
            x-stoplight:
              id: 797pius6ai8kd
            type: string
    Validation-Field:
      title: Validation Field
      x-stoplight:
        id: z814q5o5m2w2u
      type: object
      required:
        - field_key
        - data_type
        - required
        - localized_names
      properties:
        field_key:
          type: string
          x-stoplight:
            id: oaa6k1zu3v9u9
          example: document_number
          description: Unique identifier key
        document_key:
          type: string
          x-stoplight:
            id: eez6jj6zl6bwb
          example: given_names
          description: Internal field which can be ignored.
        data_type:
          x-stoplight:
            id: geb199g7xdjwa
          enum:
            - string
            - number
            - date
            - email
            - phone
            - boolean
          description: Primitive type of the value of this field.
        order:
          type: number
          x-stoplight:
            id: 4j9lmxry0i6ph
          deprecated: true
          example: 3
          description: Order position of this field.
        required:
          type: boolean
          x-stoplight:
            id: r9uo49ic6gi8a
          description: Whether this field must supplied in the `prevalidation` task.
        localized_names:
          type: object
          x-stoplight:
            id: aqxbfni0je3bi
          description: Localization map where the `key` is the country code (e.g. `en`) and the value the human readable name.
          additionalProperties:
            x-stoplight:
              id: ks9zlbc9dbvth
            type: string
            example: Document Number
        validation_rule:
          type: string
          x-stoplight:
            id: ohr1a8iwi8sh7
          description: 'Internal Field. CEL expression. '
    Document-Data-Matching-Config:
      title: Document Data Matching Configuration
      x-stoplight:
        id: 75quxl9o4ey07
      type: object
      required:
        - enabled
        - fields
      properties:
        enabled:
          type: boolean
          x-stoplight:
            id: vjmymqgy95lp1
          description: Whether the task `Document Data Matching` is enabled.
        fields:
          x-stoplight:
            id: 7xfhu7tcr6l5j
          type: array
          description: Array of validation fields.
          items:
            $ref: '#/components/schemas/Validation-Field'
            x-stoplight:
              id: 4g2eyfq99kkub
    Consent-Config:
      title: Consent Configuration
      x-stoplight:
        id: hxgd65g6omrxo
      type: object
      properties:
        enabled:
          type: boolean
          x-stoplight:
            id: opgo9drczk766
          description: Whether the task `Consent` is enabled.
        consents:
          $ref: '#/components/schemas/Consents'
          x-stoplight:
            id: fjtx228s2de04
    Task-Result:
      title: Task Result
      x-stoplight:
        id: vk81o4lo0c9cq
      type: object
      required:
        - task
        - status
        - confidence_score
        - start_time
        - end_time
      properties:
        task:
          type: string
          x-stoplight:
            id: cam6e52c94mke
          example: iddocanalysis
          description: Name of the task.
        status:
          x-stoplight:
            id: h1rdqiinejfmv
          example: FINISHED
          enum:
            - FINISHED
            - ABORTED
          description: Status of the task
        confidence_score:
          type: number
          x-stoplight:
            id: lu8v188dcvbjw
          format: float
          example: 0.97
          description: Confidence of the system.
        start_time:
          type: string
          x-stoplight:
            id: r404t3ll3pn0i
          example: '2025-11-20T10:19:13.981Z'
          description: Start date of the task (ISO 8601)
        end_time:
          type: string
          x-stoplight:
            id: 2k6bpzt29rmux
          example: '2025-11-20T10:19:52.336Z'
          description: End date of the task (ISO 8601)
        analysis_type:
          x-stoplight:
            id: piv5dyp68weuu
          enum:
            - doc
            - face
          description: Internal Field.
        case_id:
          type: string
          x-stoplight:
            id: ghqseyh5rvcdc
          deprecated: true
          example: 84a2a606-7316-4873-a924-e20f540f5c74
          description: UUID of the ID validation.
        userAgent:
          type: string
          x-stoplight:
            id: 3xyqk4djm0gsy
          description: User Agent string as supplied in the  browser's request headers of the user.
        image_urls:
          type: array
          x-stoplight:
            id: 2qo3ji41opflm
          uniqueItems: true
          description: Array of URLs that point to the `media-srv`. URLs can be called to download images.
          items:
            x-stoplight:
              id: hj7st5ebv0xkd
            type: string
        issues:
          $ref: '#/components/schemas/Analysis-Issue'
          x-stoplight:
            id: qeh88fyv3olz0
          description: Potential issues that arose during the task.
    Case-Result:
      title: Case Result
      x-stoplight:
        id: 6j7tpcyx5fdz7
      type: object
      required:
        - document
        - document_data
        - age
        - confidence_score
        - task_results
      properties:
        document:
          type: string
          x-stoplight:
            id: a8apvhfdw5sdn
          example: DEU_I_2021
          description: |-
            Unique identifier of the detected document.

            - First section is the ISO 3166-1 alpha-3 country code
            - Second section is the type of ID document
                - I = Identity Card
                - P = Passport
                - D = Driver License
                - R = Residence Permit
            - Third section is the year the document was first issued
        document_data:
          type: object
          x-stoplight:
            id: aqiph2lkf24uq
          description: Key-Value pair of the content extracted from the ID document.
        age:
          type: number
          x-stoplight:
            id: iw02d7la0c6w1
          description: 'Age of the user. '
        confidence_score:
          type: number
          x-stoplight:
            id: klvtpq64t0jik
          example: 0.78
          maximum: 1
          minimum: 0
          format: float
          description: Confidence score of the system.
        status:
          x-stoplight:
            id: 5gqmnslb1lpnx
          enum:
            - SUCCESS
            - FAILED
          description: 'Validation status. `SUCCESS` equals a validated identity, while `FAILED` equals a rejection.'
        jwt_signature:
          type: string
          x-stoplight:
            id: mt9jr6deoen3d
          description: JWT string which holds information about the id validation and acts as signature of approval.
        abort_record:
          $ref: '#/components/schemas/Abort-Record'
          x-stoplight:
            id: 21bd5r22o73gg
          description: Additional information about a potential abort of the ID validation.
        task_results:
          type: array
          x-stoplight:
            id: 32h1rxkvu5yxi
          description: Array containing the results of each task.
          items:
            $ref: '#/components/schemas/Task-Result'
            x-stoplight:
              id: ysiybw1ji4oop
    Abort-Record:
      title: Abort-Record
      x-stoplight:
        id: d5a1s03ugvl0p
      type: object
      properties:
        abort_reason:
          type: string
          x-stoplight:
            id: nt2e9obrv481o
          description: Reason why the ID validation was aborted.
          example: prevalidation failed
        abort_step:
          type: string
          x-stoplight:
            id: w4rjqiuywlvvd
          description: Step/Task in which the ID validation was aborted.
          example: prevalidate
    Analysis-Issue:
      title: Analysis-Issue
      x-stoplight:
        id: 4bjfl4lfa28xc
      type: object
      required:
        - issue_type
        - description
        - severity
        - best_frames_for_review
      properties:
        issue_type:
          type: string
          x-stoplight:
            id: 1vmnmp0y6p7ft
          description: Type of the issue.
        description:
          type: string
          x-stoplight:
            id: n6vsvnkjhyq6o
          description: Human readable description of the issue.
        severity:
          type: string
          x-stoplight:
            id: p2bpv5i840qmi
          description: Severity of the issue.
        best_frames_for_review:
          type: array
          x-stoplight:
            id: 0txqd0rwfhc1i
          description: Internal Field.
          minItems: 1
          items:
            x-stoplight:
              id: vkh2evmcb74nr
            type: integer
  responses:
    ErrorResponse:
      description: Generic error response payload returned for specific responses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    StartProcess:
      description: Response containing the process ID, case ID, execution status, and URLs for continuing the ID validation process.
      content:
        application/json:
          schema:
            type: object
            x-examples:
              Example 1:
                success: true
                status: 200
                data:
                  processId: f5105102-9003-4a41-b1f3-930714ba7897
                  caseId: b2a99592-f854-4f34-b488-9fa73e8aaaba
                  executionStatus: paused
                  user_task_url: 'https://myapp-example.cidaas.de/id-validator-webapp/processes/f5105102-9003-4a41-b1f3-930714ba7897/tasks/consent'
                  user_redirect_url: 'https://myapp-example.cidaas.de'
                  browser_redirect: false
            properties:
              success:
                type: boolean
                description: Indicates the success of the operation.
              status:
                type: integer
                description: HTTP status code.
              data:
                type: object
                properties:
                  processId:
                    type: string
                    description: UUID of the ID validation process.
                  caseId:
                    type: string
                    description: UUID of the ID validation
                  executionStatus:
                    type: string
                    description: 'Execution status of the current task. '
                  user_task_url:
                    type: string
                    description: URL on which the user can continue the current ID validation task.
                    format: uri
                  user_redirect_url:
                    type: string
                    format: uri
                    description: URL to which the user will be redirected after completing the ID validation.
                  browser_redirect:
                    type: boolean
                    description: Indicates whether the response acts as a redirect.
    ValidationResult:
      description: Response containing the detailed validation result including document data, task results, and validation status.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Validation-Result'
paths:
  /id-val-srv/processes:
    post:
      tags:
        - Invocation
      summary: Create ID validation
      description: Creates a new ID validation process based on the provided payload.
      requestBody:
        $ref: '#/components/requestBodies/Start-Process'
      security:
        - OAuth2:
            - 'cidaas:idval_process_start'
      responses:
        '200':
          $ref: '#/components/responses/StartProcess'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          description: Unauthorized - missing/invalid scope or token
        5XX:
          $ref: '#/components/responses/ErrorResponse'
      operationId: create-process
  '/id-val-srv/processes/{processID}':
    get:
      tags:
        - Status
      summary: Process Status
      description: Returns the current status of an ID validation process
      parameters:
        - name: processID
          in: path
          required: true
          schema:
            type: string
          description: UUID of the process
      security:
        - OAuth2:
            - 'cidaas:idval_process_read'
      responses:
        '200':
          description: Successfully retrieved the process status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  status:
                    type: integer
                  data:
                    $ref: '#/components/schemas/ProcessStatus'
        '401':
          description: Unauthorized - missing/invalid scope or token
        '404':
          $ref: '#/components/responses/ErrorResponse'
        5XX:
          $ref: '#/components/responses/ErrorResponse'
      operationId: get-process-status
    parameters:
      - schema:
          type: string
          format: uuid
          example: 3df810ae-66c6-4a48-80af-3d753c91518c
        name: processID
        in: path
        required: true
        description: The UUID of the ID validation process
  '/id-val-srv/idcases/{caseID}/result':
    parameters:
      - schema:
          type: string
        name: caseID
        in: path
        required: true
        description: UUID of the ID validation
    get:
      summary: Validation Result
      tags:
        - Result
      responses:
        '200':
          $ref: '#/components/responses/ValidationResult'
        '401':
          description: Unauthorized
        4XX:
          $ref: '#/components/responses/ErrorResponse'
        5XX:
          $ref: '#/components/responses/ErrorResponse'
      operationId: get-validation-result
      x-stoplight:
        id: xacjc4wyyh9wb
      security:
        - OAuth2:
            - 'cidaas:idval_result_read'
      description: Returns the result of the ID validation.
tags:
  - name: idval
    description: ID validator