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

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

Security depends on which kind of app you're integrating.

For API accounts (vendors): On successful completion of an API access request you will be issued a gateway API key that is globally unique and tied to your BC Registries account. Every request must include this API key along with your Account ID. The API key both identifies your app at the gateway and establishes your account context. No separate token is needed on your side. Access to a given API is granted per the scope of your access request; more granular Registries authorization is managed by the roles associated with your SBC Connect account ID.

For partner apps: Your app is issued a gateway API key that identifies the app itself (used by the gateway for rate limits, telemetry, and allowlisting). Account context comes from the end user's session: after the user signs in through BC Registries SSO, your backend calls our APIs with the user's bearer token plus the Account ID of the BC Registries account the user is transacting under. A single user may belong to more than one BC Registries account, so your app needs to track which account is active for each request. The API key is not linked to any specific BC Registries account; it identifies your app, not your users.

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

Payment routing depends on which kind of app is submitting the request.

For API accounts (vendors): Your BC Registries account has a payment method configured on it. When an API request that incurs a service fee is submitted with your API key and Account ID, the charge is applied to your account using that payment method.

For partner apps: The charge is applied to the BC Registries account the end user is transacting under for this request (identified by the Account ID header), using the payment method configured on that account (credit card, online banking, or pre-authorized debit). If the user belongs to multiple accounts, your app is responsible for setting the correct Account ID. Revenue collected on the partner's behalf is settled back to the partner separately, outside the API surface.

In both cases, 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.

Message Logging

ServiceBC Connect Account consumer Developer Site 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

> Learn more about Gateway Message Logging

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.