openapi: 3.1.0
info:
  title: Vistra Documents Incorporations API
  description: 'The Vistra Incorporations API enables programmatic submission of company incorporation requests in supported jurisdictions. Currently available for the British Virgin Islands (BVI) on an invite-only basis. The API supports a three-step workflow: (1) generate a pre-signed S3 document upload URL, (2) confirm document upload completion, and (3) submit the full incorporation request with entity details, stakeholders, shareholding structure, and compliance data. Authentication uses OAuth2 bearer tokens obtained from the Vistra Developer Portal.'
  version: '1.0'
  contact:
    name: Vistra Developer Support
    url: https://devportal.vistra.com/
  license:
    name: Vistra Terms of Use
    url: https://www.vistra.com/terms-of-use
  termsOfService: https://www.vistra.com/terms-of-use
servers:
- url: https://api.vistra.com
  description: Vistra Production API
security:
- OAuth2Bearer: []
tags:
- name: Incorporations
  description: Company incorporation request submission and management
paths:
  /v1/external/incorporations:
    post:
      operationId: createIncorporation
      summary: Create Incorporation
      description: Submits a company incorporation request to Vistra after all supporting documents have been uploaded and their IDs recorded. The request body includes comprehensive entity information, individual and corporate stakeholders, shareholding structure, and compliance data. This endpoint is currently available for British Virgin Islands (BVI) incorporations on an invite-only basis.
      tags:
      - Incorporations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncorporationRequest'
      responses:
        '201':
          description: Incorporation request submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncorporationResponse'
        '400':
          description: Invalid incorporation request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - API access is invite-only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable entity - validation errors in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listIncorporations
      summary: List Incorporations
      description: Returns a list of incorporation requests submitted through the API, including their current status and reference identifiers.
      tags:
      - Incorporations
      parameters:
      - name: status
        in: query
        required: false
        description: Filter by incorporation status
        schema:
          type: string
          enum:
          - pending
          - processing
          - completed
          - rejected
      - name: offset
        in: query
        required: false
        description: Pagination offset
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        required: false
        description: Number of records per page
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: List of incorporation requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncorporationList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/external/incorporations/{id}:
    get:
      operationId: getIncorporation
      summary: Get Incorporation
      description: Returns the current status and details of a specific incorporation request.
      tags:
      - Incorporations
      parameters:
      - name: id
        in: path
        required: true
        description: Incorporation request identifier
        schema:
          type: string
      responses:
        '200':
          description: Incorporation request details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncorporationResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    IndividualStakeholder:
      type: object
      description: An individual stakeholder in the incorporated entity
      required:
      - firstName
      - lastName
      - role
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        nationality:
          type: string
        role:
          type: string
          enum:
          - director
          - shareholder
          - beneficial_owner
          - secretary
        shares:
          type: integer
          description: Number of shares held (for shareholders)
        documentIds:
          type: array
          items:
            type: string
          description: IDs of identity documents for this stakeholder
    CorporateStakeholder:
      type: object
      description: A corporate entity as a stakeholder
      properties:
        companyName:
          type: string
        jurisdiction:
          type: string
        registrationNumber:
          type: string
        role:
          type: string
          enum:
          - shareholder
          - director
        shares:
          type: integer
        documentIds:
          type: array
          items:
            type: string
    ValidationError:
      type: object
      description: Validation error with field-level details
      properties:
        code:
          type: string
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    Error:
      type: object
      description: API error response
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: string
          description: Additional error details
    IncorporationRequest:
      type: object
      description: Full incorporation request including entity details, stakeholders, shareholding structure, and compliance information.
      required:
      - jurisdiction
      - companyName
      - entityType
      properties:
        jurisdiction:
          type: string
          description: Jurisdiction for incorporation (e.g. BVI)
          example: BVI
        companyName:
          type: string
          description: Proposed company name
        entityType:
          type: string
          description: Type of entity to incorporate
          enum:
          - business_company
          - llc
          - limited_partnership
        shareStructure:
          $ref: '#/components/schemas/ShareStructure'
        registeredAgent:
          $ref: '#/components/schemas/RegisteredAgent'
        individuals:
          type: array
          description: Individual stakeholders (directors, shareholders, beneficial owners)
          items:
            $ref: '#/components/schemas/IndividualStakeholder'
        corporates:
          type: array
          description: Corporate stakeholders
          items:
            $ref: '#/components/schemas/CorporateStakeholder'
        documentIds:
          type: array
          description: IDs of previously uploaded supporting documents
          items:
            type: string
        notes:
          type: string
          description: Additional notes or special instructions
    IncorporationResponse:
      type: object
      description: Response after submitting an incorporation request
      properties:
        id:
          type: string
          description: Unique incorporation request identifier
        status:
          type: string
          description: Current status of the incorporation request
          enum:
          - pending
          - processing
          - completed
          - rejected
        companyName:
          type: string
        jurisdiction:
          type: string
        submittedAt:
          type: string
          format: date-time
        estimatedCompletionDate:
          type: string
          format: date
        referenceNumber:
          type: string
          description: Vistra's internal reference number
    IncorporationList:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/IncorporationResponse'
    ShareStructure:
      type: object
      description: Shareholding structure for the company
      properties:
        authorizedShares:
          type: integer
          description: Total number of authorized shares
        parValue:
          type: number
          description: Par value per share
        currency:
          type: string
          description: Currency for par value (e.g. USD)
    RegisteredAgent:
      type: object
      description: Registered agent details
      properties:
        name:
          type: string
        address:
          type: string
        jurisdiction:
          type: string
  securitySchemes:
    OAuth2Bearer:
      type: http
      scheme: bearer
      description: OAuth2 bearer token obtained from the Vistra Developer Portal. Include in the Authorization header as "Bearer {token}".
externalDocs:
  description: Vistra Incorporations API Documentation
  url: https://help.vistra.com/en/articles/10351085-vistra-incorporations-api-british-virgin-islands