Skip to main content
All CollectionsAPI
Vistra Incorporations API - British Virgin Islands
Vistra Incorporations API - British Virgin Islands

Streamline BVI entity incorporations with Vistra Incorporations API. Learn how to authenticate, upload documents, and automate compliance with detailed examples and step-by-step guidance.

Davin Wu avatar
Written by Davin Wu
Updated over 2 months ago

Vistra BVI Incorporation API Documentation

Welcome to the Vistra API documentation. This API allows external partners to integrate and streamline the incorporation process for BVI entities.

Follow the steps below to understand how to authenticate, upload documents, and create an incorporation.

Authentication

Currently, the Vistra Incorporations API is currently available on an invite-only basis.

To log in:

  1. Head to the Vistra Developer Portal

  2. Click on "Login / Sign up"

  3. Click on "Sign in with Email"

  4. Enter email address

  5. Get verification code from email

  6. Enter verification code

  7. User will be redirected to developer portal once done

To use the API, developers must:

  1. Create an Application in the Vistra Developer Portal.

  2. Generate API Credentials (Client ID and Secret).

  3. Use the credentials to obtain an access token using the OAuth2 flow.

  4. Include the token in the Authorization header of all requests:

Authorization: Bearer <ACCESS_TOKEN>

Workflow Overview

The incorporation workflow involves the following steps:

  1. Generate a Document Upload URL (/v1/external/documents/upload-url).

  2. Upload the Document to S3 using the pre-signed URL.

  3. Complete the Document Upload (/v1/external/documents/{id}/upload-complete) to notify Vistra.

  4. Repeat the document upload process for all required documents.

  5. Create an Incorporation (/v1/external/incorporations) with the uploaded document IDs.

API Endpoints

1. Generate Document Upload URL

Endpoint: POST /v1/external/documents/upload-url

  • Use this endpoint to generate a pre-signed S3 URL for uploading a document.

Request Example

{
 "fileName": "proof_of_address.pdf",
 "type": "PROOF_OF_ADDRESS"
}

Response Example

{
 "documentId": "35d2b9c6-2a29-4cb4-93dd-559b38f2a3d3",
 "uploadUrl": "https://cloudfront.net/yourfilehere.pdf
}

Important Notes

  • The pre-signed URL is valid for 1 minute. Ensure the document is uploaded promptly.

  • Save the documentId as it is needed for future requests.

2. Complete Document Upload by ID

Endpoint: POST /v1/external/documents/{id}/upload-complete

  • Once a document is uploaded, notify Vistra using this endpoint to complete the upload process.

Path Parameter

  • id: The documentId obtained from the “Generate Document Upload URL” response.

Request Example

{
 "documentId": "35d2b9c6-2a29-4cb4-93dd-559b38f2a3d3"
}

Response Example

{
 "documentId": "35d2b9c6-2a29-4cb4-93dd-559b38f2a3d3",
 "fileName": "proof_of_address.pdf",
 "fileLink": "https://cloudfront.net/yourfilehere.pdf"
}

Important Notes

  • Both the “Generate Document Upload URL” and “Complete Document Upload by ID” steps must be performed for each document.

3. Create an Incorporation

Endpoint: POST /v1/external/incorporations

  • Use this endpoint to submit incorporation details after all documents have been uploaded and their IDs have been recorded.

Request Example

{
  "countryCode": "BVI",
  "stateCode": "VG",
  "reportingCurrency": "USD",
  "entityName": [
    "MyNewEntity"
  ],
  "entityCnName": [
    "我的新实体"
  ],
  "entityDescription": "An investment company specializing in property development.",
  "entityType": "LIMITED_LIABILITY_COMPANY",
  "registeredAddress": {
    "address1": "123 Palm Grove Avenue",
    "address2": "Suite 200",
    "city": "Road Town",
    "countryCode": "BVI",
    "state": "Tortola",
    "postalCode": "VG1110"
  },
  "sgSsicCode": "68101",
  "entityDocuments": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "natureOfBusiness": "PROPERTY_INVESTMENT",
  "natureOfBusinessOthers": "",
  "locationOfBusinessActivity": "Road Town, Tortola, BVI",
  "hasDigitalCurrencyInvolved": false,
  "sourceOfFunds": "INVESTOR_CAPITAL",
  "estimatedAnnualRevenue": "ZERO_TO_FIFTY_THOUSAND",
  "totalNumberOfShares": 1000,
  "totalAmountOfShares": 100000,
  "totalAmountOfSharesCurrencyCode": "USD",
  "individuals": [
    {
      "isDirector": true,
      "isShareholder": true,
      "isBeneficialOwner": true,
      "title": "MR",
      "firstName": "John",
      "middleName": "A",
      "lastName": "Doe",
      "email": "[email protected]",
      "identificationType": "PASSPORT_NUMBER",
      "identificationNumber": "A12345678",
      "nationality": "American",
      "countryOfBirth": "USA",
      "countryOfResidency": "USA",
      "residencyStatus": "FOREIGNER",
      "dateOfBirth": "1980-01-01",
      "phoneCountryCode": "+1",
      "phoneNumber": "5551234567",
      "address1": "456 Elm Street",
      "address2": "Apartment 4B",
      "addressCity": "New York",
      "addressCountryCode": "USA",
      "addressPostalCode": "10001",
      "addressState": "NY",
      "proofOfIdentificationDocumentId": "123e4567-e89b-12d3-a456-426614174000",
      "proofOfAddressDocumentId": "123e4567-e89b-12d3-a456-426614174001",
      "passportDocumentId": "123e4567-e89b-12d3-a456-426614174002",
      "driversLicenseDocumentId": "123e4567-e89b-12d3-a456-426614174003",
      "interestHeldPercentage": 50,
      "sourceOfWealth": "EMPLOYMENT",
      "sourceOfWealthOthers": "",
      "wealthSourcesDescription": "Executive salary and stock options.",
      "registrationOfDirectorsDocumentId": "123e4567-e89b-12d3-a456-426614174004",
      "businessRegistrationCertificateDocumentId": "123e4567-e89b-12d3-a456-426614174005",
      "payrollDocumentId": "123e4567-e89b-12d3-a456-426614174006",
      "employmentBankStatementDocumentId": "123e4567-e89b-12d3-a456-426614174007",
      "financialInformationDocumentId": "123e4567-e89b-12d3-a456-426614174008",
      "investmentStatementDocumentId": "123e4567-e89b-12d3-a456-426614174009",
      "rentalBankStatementDocumentId": "123e4567-e89b-12d3-a456-426614174010",
      "buyAndSellAgreementDocumentId": "123e4567-e89b-12d3-a456-426614174011",
      "loanAgreementDocumentId": "123e4567-e89b-12d3-a456-426614174012",
      "shares": [
        {
          "sharePercentage": 50,
          "type": "COMMON"
        }
      ]
    }
  ],
  "corporates": [
    {
      "isDirector": true,
      "isShareholder": true,
      "isBeneficialOwner": true,
      "companyName": "Acme Holdings Ltd.",
      "companyCountryCode": "SG",
      "companyStateCode": "SG",
      "governmentBusinessId": "SG12345678",
      "title": "MR",
      "firstName": "James",
      "middleName": "B",
      "lastName": "Smith",
      "email": "[email protected]",
      "certificateOfIncorporationDocumentId": "123e4567-e89b-12d3-a456-426614174013",
      "businessProfileDocumentId": "123e4567-e89b-12d3-a456-426614174014",
      "groupOwnershipStructureChartDocumentId": "123e4567-e89b-12d3-a456-426614174015",
      "previousCompanyName": "Smith Enterprises",
      "interestHeldPercentage": 50,
      "sourceOfWealth": "INVESTMENT_INCOME",
      "sourceOfWealthOthers": "",
      "wealthSourcesDescription": "Dividends from holdings.",
      "registrationOfDirectorsDocumentId": "123e4567-e89b-12d3-a456-426614174016",
      "businessRegistrationCertificateDocumentId": "123e4567-e89b-12d3-a456-426614174017",
      "payrollDocumentId": "123e4567-e89b-12d3-a456-426614174018",
      "employmentBankStatementDocumentId": "123e4567-e89b-12d3-a456-426614174019",
      "financialInformationDocumentId": "123e4567-e89b-12d3-a456-426614174020",
      "investmentStatementDocumentId": "123e4567-e89b-12d3-a456-426614174021",
      "rentalBankStatementDocumentId": "123e4567-e89b-12d3-a456-426614174022",
      "buyAndSellAgreementDocumentId": "123e4567-e89b-12d3-a456-426614174023",
      "loanAgreementDocumentId": "123e4567-e89b-12d3-a456-426614174024",
      "shares": [
        {
          "sharePercentage": 50,
          "type": "PREFERRED"
        }
      ]
    }
  ]
}

Response Example

{
 "incorporationId": "9f1346c0-ee07-4ec1-b82c-b7096613a735"
}

Important Notes

  • Ensure that all fields marked as required in the Swagger schema are provided.

  • Use the documentId from the previous steps in fields ending with DocumentId.

Additional Information

Field Mappings

Developers must map their internal data to the corresponding Vistra API fields. For example:

  • proofOfIdentificationDocumentId → Document ID for proof of identification.

  • proofOfAddressDocumentId → Document ID for proof of address.

  • Other document fields as specified in the incorporation request schema.

Common Errors

  • 401 Unauthorized: Ensure the access token is included and valid.

  • 400 Bad Request: Check for missing or invalid fields in the request payload.

  • 422 Unprocessable Entity: Ensure the document upload process is completed for all required documents.

Changelog

  • v1.0: Initial release of the Vistra API.

Did this answer your question?