openapi: 3.0.1
info:
  title: Prove Auth Identity Verification API
  description: 'Phone-centric identity verification and authentication API. The Prove API (v3) uses a consumer''s mobile phone number and cryptographic possession signals to power the Pre-Fill verification flow (start, validate, challenge, complete), Unified Authentication / Trust Score (unify, unify-bind, unify-status), identity discovery (discover, fetch), phone-based Auth, and a persistent Identity Manager. All endpoints are OAuth 2.0 (client-credentials) secured; obtain a Bearer access token from the /token endpoint and send it as `Authorization: Bearer <token>` on every subsequent request.'
  termsOfService: https://www.prove.com/legal/terms
  contact:
    name: Prove Developer Support
    url: https://developer.prove.com
  version: '3.0'
servers:
- url: https://api.prove.com/v3
  description: Production
- url: https://platform.proveapis.com/v3
  description: Production (platform host)
- url: https://platform.uat.proveapis.com/v3
  description: UAT / Sandbox
security:
- bearerAuth: []
tags:
- name: Identity Verification
  description: Ordered Pre-Fill verification flow - start, validate, challenge, complete.
paths:
  /start:
    post:
      operationId: v3StartRequest
      tags:
      - Identity Verification
      summary: Start a Pre-Fill verification flow
      description: Initiates the identity verification session against a mobile phone number, indicates whether the session is desktop or mobile, and returns a correlation ID plus an auth token and the set of allowed next calls.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3StartRequest'
      responses:
        '200':
          description: Flow started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3StartResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /validate:
    post:
      operationId: v3ValidateRequest
      tags:
      - Identity Verification
      summary: Validate the started flow
      description: Validates the initiated flow against the correlation ID returned by /start and confirms phone possession. The response Next field indicates whether a challenge is required before completing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ValidateRequest'
      responses:
        '200':
          description: Flow validated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3FlowResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /challenge:
    post:
      operationId: v3ChallengeRequest
      tags:
      - Identity Verification
      summary: Challenge the customer
      description: When /validate returns `v3-challenge` in its Next field, submit a knowledge challenge (date of birth and/or last four of SSN) to raise assurance before completing the flow.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3ChallengeRequest'
      responses:
        '200':
          description: Challenge evaluated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3FlowResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /complete:
    post:
      operationId: v3CompleteRequest
      tags:
      - Identity Verification
      summary: Complete the Pre-Fill flow
      description: Final call in the flow. Submits the customer's claimed identity for real-time reconciliation against the phone number and returns the IDV / KYC evaluation and prefilled identity attributes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V3CompleteRequest'
      responses:
        '200':
          description: Flow completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3CompleteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Individual:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dob:
          type: string
        ssn:
          type: string
        emailAddresses:
          type: array
          items:
            type: string
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    V3ValidateRequest:
      type: object
      required:
      - correlationId
      properties:
        correlationId:
          type: string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            additionalProperties: true
    V3CompleteResponse:
      type: object
      properties:
        success:
          type: boolean
        evaluation:
          type: string
          description: Overall flow evaluation result.
        idv:
          type: object
          additionalProperties: true
          description: Identity verification result and reconciled attributes.
        kyc:
          type: object
          additionalProperties: true
          description: KYC screening result.
        next:
          $ref: '#/components/schemas/Next'
    V3StartResponse:
      type: object
      properties:
        success:
          type: boolean
        correlationId:
          type: string
          description: Session correlation ID passed to all subsequent flow calls.
        authToken:
          type: string
        next:
          $ref: '#/components/schemas/Next'
    V3StartRequest:
      type: object
      required:
      - flowType
      - phoneNumber
      properties:
        flowType:
          type: string
          enum:
          - desktop
          - mobile
          description: Whether the session originates on desktop or mobile.
        phoneNumber:
          type: string
          description: Customer mobile phone number.
        finalTargetURL:
          type: string
          format: uri
          description: URL to redirect to at the end of a desktop (Instant Link) flow.
        emailAddress:
          type: string
        smsMessage:
          type: string
          description: Customizable SMS body; use
        ipAddress:
          type: string
        dob:
          type: string
          description: Date of birth (YYYY-MM-DD) used to seed reconciliation.
        ssn:
          type: string
          description: Full or last-four SSN.
        allowOTPRetry:
          type: boolean
    Address:
      type: object
      properties:
        address:
          type: string
        city:
          type: string
        region:
          type: string
        postalCode:
          type: string
    V3ChallengeRequest:
      type: object
      required:
      - correlationId
      properties:
        correlationId:
          type: string
        dob:
          type: string
          description: Date of birth (YYYY-MM-DD).
        ssn:
          type: string
          description: Last four of SSN.
    V3FlowResponse:
      type: object
      properties:
        success:
          type: boolean
        correlationId:
          type: string
        next:
          $ref: '#/components/schemas/Next'
    V3CompleteRequest:
      type: object
      required:
      - correlationId
      - individual
      properties:
        correlationId:
          type: string
        individual:
          $ref: '#/components/schemas/Individual'
    Next:
      type: object
      additionalProperties:
        type: string
      description: Map of allowed next operations for the flow (for example `v3-challenge`, `v3-complete`).
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid, or expired access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 client-credentials Bearer access token obtained from POST /token.
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.prove.com/v3/token
          scopes: {}