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.

Short NameDescriptionSANDBOX VersionPROD Version
PayPay Api1.0.01.0.0
PPRPersonal Property Registry API1.0.01.0.0
BusinessBusiness Registry API
Registry SearchRegistry Search API
MHRManufacutured Home Registry API1.0.01.0.0

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

Environment Base URL
MOCK https://bcregistry-bcregistry-mock.apigee.net
SANDBOX https://bcregistry-sandbox.apigee.net
PRODUCTION https://bcregistry-prod.apigee.net

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.

Status Code Description
200 Successful request and response.
201 Successfully created.
400 Bad Request. The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
401 Unauthorized. Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The user does not have valid authentication credentials for the target resource.
404 Not Found. The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
422 Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors. Most likely the value of a data element such as a code is invalid.
500 Internal Server Error. A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
503 Service Unavailable. The server cannot handle the request (because it is overloaded or down for maintenance). Response when an API is temporarily unavailable as part of a scheduled release.

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.

> Learn more about Gateway Analytics Reports


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

> 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.

Date Description
2022-01-17 Update the API Release Management section.