Opkit Patients API

openapi: 3.0.1
info:
  title: Opkit API
  description: >-
    REST API for Opkit, an automated health insurance verification platform for
    telehealth companies and virtual medical practices. The API exposes
    eligibility inquiries, benefits, payers, patients, and webhooks. Requests
    are authenticated with a Bearer API key and all payloads are JSON over
    HTTPS.


    Provenance note: Opkit's platform appears to have been decommissioned after
    the company was acqui-hired by 11x in late 2024, and the live documentation
    at docs.opkit.co and the API host api.opkit.co are no longer reachable. This
    specification is reconstructed from Opkit's publicly described resource model
    (eligibility inquiries, benefits, payers, patients, webhooks; Bearer-key
    auth; base URL https://api.opkit.co/v1). Endpoint paths and object fields
    that could not be verified against live documentation are modeled
    conservatively along standard RESTful conventions and should be reconciled
    against authoritative Opkit documentation if it becomes available. No values
    are presented as guaranteed-accurate beyond the verified auth scheme and
    base URL.
  contact:
    name: Opkit
    url: https://www.opkit.co
  version: '1.0'
servers:
  - url: https://api.opkit.co/v1
    description: Opkit API v1 production base URL (host no longer resolving as of catalog date).
security:
  - bearerAuth: []
tags:
  - name: Eligibility Inquiries
    description: Create and retrieve real-time insurance eligibility inquiries.
  - name: Benefits
    description: Read structured benefit details from completed eligibility inquiries.
  - name: Payers
    description: Look up insurance carriers (payers) Opkit connects to.
  - name: Patients
    description: Manage patient records that are the subject of eligibility inquiries.
  - name: Webhooks
    description: Register and manage webhook endpoints for event notifications.
paths:
  /eligibility-inquiries:
    get:
      operationId: listEligibilityInquiries
      tags:
        - Eligibility Inquiries
      summary: List eligibility inquiries
      description: Returns a paginated list of eligibility inquiries on the account.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of eligibility inquiries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityInquiryList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEligibilityInquiry
      tags:
        - Eligibility Inquiries
      summary: Create an eligibility inquiry
      description: >-
        Submits a real-time insurance eligibility inquiry for a patient against a
        payer. Inquiries are resolved asynchronously; poll the inquiry or
        subscribe to a webhook to receive the completed result and benefits.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EligibilityInquiryCreateRequest'
      responses:
        '201':
          description: The created eligibility inquiry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityInquiry'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /eligibility-inquiries/{id}:
    get:
      operationId: getEligibilityInquiry
      tags:
        - Eligibility Inquiries
      summary: Retrieve an eligibility inquiry
      description: Retrieves a single eligibility inquiry, including its status and benefits when complete.
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: The requested eligibility inquiry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityInquiry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /benefits:
    get:
      operationId: listBenefits
      tags:
        - Benefits
      summary: List benefits
      description: >-
        Returns benefit records derived from completed eligibility inquiries,
        optionally filtered by eligibility inquiry.
      parameters:
        - name: eligibility_inquiry_id
          in: query
          description: Filter benefits to a specific eligibility inquiry.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of benefit records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /benefits/{id}:
    get:
      operationId: getBenefit
      tags:
        - Benefits
      summary: Retrieve a benefit
      description: Retrieves a single structured benefit record.
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: The requested benefit record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Benefit'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payers:
    get:
      operationId: listPayers
      tags:
        - Payers
      summary: List payers
      description: Returns the list of insurance carriers (payers) Opkit connects to, with optional search.
      parameters:
        - name: query
          in: query
          description: Free-text search to match payers by name.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of payers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayerList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /payers/{id}:
    get:
      operationId: getPayer
      tags:
        - Payers
      summary: Retrieve a payer
      description: Retrieves a single payer by its identifier.
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: The requested payer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /patients:
    get:
      operationId: listPatients
      tags:
        - Patients
      summary: List patients
      description: Returns a paginated list of patient records on the account.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A list of patients.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPatient
      tags:
        - Patients
      summary: Create a patient
      description: Creates a patient record to use as the subject of eligibility inquiries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientCreateRequest'
      responses:
        '201':
          description: The created patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patients/{id}:
    get:
      operationId: getPatient
      tags:
        - Patients
      summary: Retrieve a patient
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: The requested patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePatient
      tags:
        - Patients
      summary: Update a patient
      parameters:
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientUpdateRequest'
      responses:
        '200':
          description: The updated patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhook endpoints
      description: Returns the webhook endpoints registered on the account.
      responses:
        '200':
          description: A list of webhook endpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook endpoint
      description: Registers a URL to receive event notifications such as eligibility inquiry completion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
      responses:
        '201':
          description: The created webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/{id}:
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Retrieve a webhook endpoint
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: The requested webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook endpoint
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '204':
          description: The webhook endpoint was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Provide your Opkit API key as a Bearer token in the Authorization
        header: `Authorization: Bearer YOUR_API_KEY`.
  parameters:
    PathId:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    StartingAfter:
      name: starting_after
      in: query
      required: false
      description: Cursor for pagination; the id of the last object on the previous page.
      schema:
        type: string
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed or the API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: A machine-readable error type.
            message:
              type: string
              description: A human-readable description of the error.
    EligibilityInquiryCreateRequest:
      type: object
      required:
        - patient_id
        - payer_id
      properties:
        patient_id:
          type: string
          description: The id of the patient to verify.
        payer_id:
          type: string
          description: The id of the payer to verify coverage against.
        member_id:
          type: string
          description: The patient's member or subscriber identifier on the payer.
        service_type:
          type: string
          description: The benefit/service type to check (e.g. health benefit plan coverage).
        metadata:
          type: object
          additionalProperties: true
          description: Arbitrary key/value metadata to associate with the inquiry.
    EligibilityInquiry:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: eligibility_inquiry
        status:
          type: string
          description: Lifecycle status of the inquiry.
          enum:
            - pending
            - processing
            - completed
            - error
        patient_id:
          type: string
        payer_id:
          type: string
        member_id:
          type: string
        benefits:
          type: array
          description: Structured benefits, populated once the inquiry completes.
          items:
            $ref: '#/components/schemas/Benefit'
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        metadata:
          type: object
          additionalProperties: true
    EligibilityInquiryList:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/EligibilityInquiry'
        has_more:
          type: boolean
    Benefit:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: benefit
        eligibility_inquiry_id:
          type: string
        coverage_status:
          type: string
          description: Whether the plan is active.
          enum:
            - active
            - inactive
            - unknown
        network_status:
          type: string
          description: Whether the patient is in- or out-of-network.
          enum:
            - in_network
            - out_of_network
            - unknown
        plan_name:
          type: string
        copay:
          type: number
          nullable: true
        coinsurance:
          type: number
          nullable: true
        deductible:
          type: number
          nullable: true
        deductible_remaining:
          type: number
          nullable: true
        out_of_pocket_max:
          type: number
          nullable: true
    BenefitList:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Benefit'
        has_more:
          type: boolean
    Payer:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: payer
        name:
          type: string
          description: The display name of the insurance carrier.
    PayerList:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payer'
        has_more:
          type: boolean
    PatientCreateRequest:
      type: object
      required:
        - first_name
        - last_name
        - date_of_birth
      properties:
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        metadata:
          type: object
          additionalProperties: true
    PatientUpdateRequest:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        metadata:
          type: object
          additionalProperties: true
    Patient:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: patient
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        created_at:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
    PatientList:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Patient'
        has_more:
          type: boolean
    WebhookCreateRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: The HTTPS endpoint that will receive event notifications.
        events:
          type: array
          description: Event types to subscribe to (e.g. eligibility inquiry completion).
          items:
            type: string
    Webhook:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: webhook
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
    WebhookList:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        has_more:
          type: boolean