BC Registries APIs

The BC Registries APIs are HTTP-based RESTful APIs. Request and response bodies are formatted in JSON. The API specifications are written in OpenAPI (OAS) version 3.x.

List of APIs

Click on the Short Name to see more.

The SANDBOX maintenance window is Sunday mornings between 8 am and 12 pm Pacific time.

API Common Information

The information below applies to all BC Registries APIs.

Environments

The Mock environment requires an API key, does not charge a fee, and only works with the example requests defined in the API specifications.

Status and Error Responses

The APIs use HTTP Status Codes to indicate success or failure. The table below lists the common status codes.

A 400 or 500 level status code will include a an error response containing an errorMessage and an optional rootCause. Below is an example of a BC Registries API gateway error: a 401 Unauthorized response body when submitting a request with an invalid API key:

{
    "errorMessage": "API security error: API key check failed.",
    "rootCause": "{\"fault\":{\"faultstring\":\"Invalid ApiKey\",\"detail\":{\"errorcode\":\"oauth.v2.InvalidApiKey\"}}}"
}

Here is a 400 Bad Request response body example when submitting a payment API invalid fee code request:

{
    "errorMessage": "API backend third party service error.",
    "rootCause": "{\"detail\": \"Invalid Corp Type or Filing Type.\", \"title\": \"Invalid Request\", \"type\": \"INVALID_CORP_OR_FILING_TYPE\"}"
}

How Security Works

On successful completion of an API access request you will be issued a gateway API key that is globally unique and tied to your security account. As part of the access request you specify which APIs you want to use. Gateway authentication requires that your API key is included with each request, and that the API key has permission to accesss the API that the request is for. More granular Registries authorization is managed by the security role(s) associated with your BC OnLine account Id, which is linked to both your security account and your API key.

As part of the access request you will receive instructions on maintaining your API key: how to request a new one and how to replace an existing one for an API gateway environment.

How Payment Works

Your BC OnLine Account has a payment method associated with it. Your API key is linked to your BC OnLine Account ID. When an API request for which there is a service fee is submitted with your API key and your BC OnLine Account ID, a charge is applied to your acount using the payment method you set up. The API response body includes a payment invoice identifier and a relative path to the payment receipt. For example:

  "payment": {
    "receipt": "/api/v1/payment-requests/2198743/receipts",
    "invoiceId": "2198743"
  }

The invoiceId is the BC Registries payment record identifier. The receipt is a corresponding relative path to the BC Registries Payment API to retrieve payment receipt information for your API transaction.

Analytics Reports

BC OnLine Account consumer API Gateway activity is tracked for up to 30 days in the past. Daily and weekly reports are available in JSON or CSV formats. Basic metrics available in these reports include:

• response status
• response time
• API name
• traffic
• errors

Once you have received the daily or weekly report data, you can import that data into your own data visualization tools or analytics system.

Message Logging

BC Online Account consumer API Gateway message logging is available by account ID and Gateway API. A dedicated message log archive is created for an account ID and API combination. It requires a Google Cloud Platform (GCP) account and project configured with permission to view the account message log. Message log entries include the following properties:

• request timestamp
• request method
• request path
• response status code
• request payload
• response payload

API Release Management

Major Version Releases

The BC Registries APIs follow Semantic Versioning. Major versions of an API may be released in March or September. The exception is an initial release, which has no such restriction. A new version is defined as an increment in the "vx" value of an API base path, where "x" is the version number. The initial version is "v1".

• Up to 2 major versions are concurrently supported, meaning that when version 3 is released version 1 will no longer be available.
• A major release may include:
  • The removal of an existing endpoint.
  • A change to a schema definition for an existing endpoint.
  • Cumulative enhancements or fixes for one or more existing endpoints.
• An API release may be skipped in a given release window if there are no changes within the previous 6 months.
• A major version release will be available in the SANDBOX environment at least 1 month prior to the release date.

Minor Releases

Minor Releases may occur outside the major version release schedule. A minor release will not include:

• A change to an existing API endpoint definition.
• A change to an existing API schema definitions.

A minor release may include a significant enhancement, such as:

• Adding a new endpoint.
• Adding a new schema definition as part of adding a new endpoint.
• Addding a new type to an existing endpoint, such as a new Financing Statement registration type.

A minor version release will be available in the SANDBOX environment at least 1 month prior to the PRODUCTION release.

Patch Releases

Outside of the above major version release schedule, minor fixes to an existing version of an API may be published as a patch release if:

• No change is made to the API endpoint definitions.
• No change is made to the API schema definitions.

For example, changing the validation rules for a Financing Statement registration type may be a candidate for a patch release.

Changes included in a patch release are described in the API's "API Version History" section.

When possible, a patch release will be available in the SANDBOX environment at least 1 week prior to the PRODUCTION release.

Page History

Updates of note to this page are recorded here.