Coincover Verification API

openapi: 3.2.0
info:
  title: Coincover Verification API
  x-refined-note:
  - x-authored-by differs across the merged source definitions and was not carried
  - x-engine differs across the merged source definitions and was not carried
  - x-evidence-tiers differs across the merged source definitions and was not carried
  - x-generated differs across the merged source definitions and was not carried
  - x-generated-from differs across the merged source definitions and was not carried
  - x-generator differs across the merged source definitions and was not carried
  - x-provenance differs across the merged source definitions and was not carried
  - x-sources differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Verification across 2 of this provider''s published API definitions: coincover-retail-openapi-openapi.json, coincover-openapi-generated.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://orchestrator.control.coincover.com
  description: Production server
- url: https://orchestrator.uat-control.coincover.com
  description: Development server
- url: https://service.uat-keys.coincover.com
tags:
- name: Verification
  description: Start, check, and simulate biometric identity verification.
paths:
  /v1/verification/start:
    post:
      summary: Start identity verification
      description: Initiates a new identity verification workflow and returns a Verification ID. The user will use this verification_id to spin up a front-end SDK that will guide the user through the identity verification workflow.
      operationId: startVerification
      tags:
      - Verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationStartRequest'
      responses:
        '200':
          description: Verification started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationId'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
    servers:
    - url: https://orchestrator.control.coincover.com
      description: Production server
    - url: https://orchestrator.uat-control.coincover.com
      description: Development server
  /v1/verification/status:
    get:
      summary: Get verification status
      description: 'Retrieves the current status of a biometric verification. The status can be in multiple states: ''pending'' (initial state), ''approved'' (all verifications passed), ''declined'' (verifications failed), or ''review'' (marked for manual review).'
      operationId: getVerificationStatus
      tags:
      - Verification
      parameters:
      - name: verification_id
        in: query
        required: true
        schema:
          type: string
        description: Verification ID to check status for
        example: inq_abc123xyz
      responses:
        '200':
          description: Verification status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationStatus'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
    servers:
    - url: https://orchestrator.control.coincover.com
      description: Production server
    - url: https://orchestrator.uat-control.coincover.com
      description: Development server
  /v1/verification/simulate:
    post:
      summary: Simulate biometric verification events
      description: Simulates biometric verification events for testing in non-production environments.
      operationId: simulateVerification
      tags:
      - Verification
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationSimulateRequest'
      responses:
        '200':
          description: Biometric verification event simulated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationSimulateResponse'
    servers:
    - url: https://orchestrator.control.coincover.com
      description: Production server
    - url: https://orchestrator.uat-control.coincover.com
      description: Development server
  /v1/verification/{verificationid}:
    post:
      operationId: post_v1_verification_verificationid
      tags:
      - Verification
      summary: Simulating outcomes
      x-source: https://developer.coincover.com/retail-recovery/testing.md
      parameters:
      - name: verificationid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1VerificationVerificationidRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
        collapsed_from: 2 example path(s) differing only at verificationId
      security:
      - bearer: []
    servers:
    - url: https://service.uat-keys.coincover.com
components:
  schemas:
    VerificationStartRequest:
      type: object
      properties:
        user_identifier:
          type: string
          description: User identifier (REQUIRED)
          example: john.doe@example.com
      required:
      - user_identifier
    VerificationId:
      type: object
      properties:
        verification_id:
          type: string
          description: Unique identifier for the biometric verification
          example: inq_abc123xyz
      required:
      - verification_id
    VerificationStatus:
      type: object
      properties:
        verification_id:
          type: string
          description: Unique identifier for the biometric verification
          example: inq_abc123xyz
        status:
          type: string
          enum:
          - pending
          - approved
          - declined
          - review
          description: Status of the biometric verification
          example: approved
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the status was last updated
          example: '2024-01-15T10:30:00Z'
      required:
      - verification_id
      - status
    VerificationSimulateRequest:
      type: object
      description: Request payload for simulating biometric verification events for testing in non-production environments.
      properties:
        verification_id:
          type: string
          description: Biometric verification ID to simulate an action for.
          example: inq_abc123xyz
        action:
          type: string
          description: Biometric verification simulation action type.
          enum:
          - start_inquiry
          - complete_inquiry
          - fail_inquiry
          - expire_inquiry
          - mark_for_review_inquiry
          - approve_inquiry
          - decline_inquiry
          example: approve_inquiry
      required:
      - verification_id
      - action
    VerificationSimulateResponse:
      type: object
      description: Response payload from the verification simulation endpoint.
      properties:
        ok:
          type: boolean
          description: Indicates whether the simulation request was processed successfully.
          example: true
        inquiryId:
          type: string
          description: The biometric verification ID that was simulated.
          example: inq_abc123xyz
      required:
      - ok
      - inquiryId
    GetV1VerificationStatusResponse:
      type: object
      properties:
        verification_id:
          type: string
        status:
          type: string
          description: One of pending, approved, declined, review
        updated_at:
          type: string
    PostV1VerificationVerificationidRequest:
      type: object
      properties:
        verification_id:
          type: string
        action:
          type: string
          description: see table below
      required:
      - verification_id
      - action
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication and authorization
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: ID token as Bearer token
    bearer:
      type: http
      scheme: bearer
x-refined-from:
- coincover-retail-openapi-openapi.json
- coincover-openapi-generated.yml