Personal Property Registry API
Overview
The Personal Property Registry (PPR) is a centralised, electronic register where details of security interests in personal property can be registered and searched. The PPR API provides a real-time, secure, direct link between your business systems and the PPR.
With this API you can submit the following transactions:
- Search for Personal Property information
- Register an interest or lien as a Financing Statement
- Amend a Financing Statement
- Renew a Financing Statement
- Discharge a Financing Statement
Note: All requests must include a BC Registries issued API key and an Account ID.
View the API
View the definition and select a path to try it out. To submit a request you will need an API key and an account ID, which are obtained as part of completing anaccess request. To set your session API key, click on the top, right AUTHORIZE button and under API Key Auth enter your key value. Click on AUTHORIZE, then OK.
A Note on Search Fees
A service fee is charged for each new search request (Search Step 1 in the Quick Reference table).
Large Search Result Reports
If the number of Financing Statements in the requested Search Results (Search Step 2 in the Quick Reference table) is greater than 75, and the request format is application/pdf, then the report creation is asynchronous. A callback URL (request parameter "callbackURL") is required. A notification will be sent to the callback URL indicating that the report is available for retrieval with a GET request. Here is an example of the notification body:
{
"id": 99999,
"getReportURL": "https://bcregistry-sandbox.apigee.net/ppr/api/v1/search-results/99999"
}
- The callback URL must be encoded.
- If you want the search results in a PDF format, and the number of Financing Statements in the results is greater than 75, then the Search Step 2 request headers Accept property must be application/pdf.
- Depending on the size of the results, the report may take up to 20 minutes to generate.
Reports for Registrations With a Large Data Size
Both Verification Statement Registrations and Search Results reports may contain individual registrations with a large amount of data - typically hundreds of serial collateral - resulting in reports that are hundreds of pages in length. Such reports take too long to generate as a real time request. As part of completing a registration or completing Search Step 2, the API queues the report request and returns a JSON response with a getReportURL property. When the report is available it can be downloaded from the PPR application Registrations or Searches tables, or with a subsequent API GET request. In the latter case, if the queued report is not yet available the API returns a 400 response.
As of version 1.2.5, a callback URL will be used in a search results report request if it is submitted and the response JSON is over 220KB in size, which corresponds to a report of approximatedly 150 pages or more. See the previous Large Search Results Report section for instructions on including a callback URL in a search results request.
Only include a callbackURL in the request if one of the above conditions is true.
API Quick Reference
| Endpoint Path | Description |
|---|---|
| GET /ppr/api/v1/drafts | Get a list of existing drafts for your account. Use the optional "type" query parameter to filter by draft type. If no parameter is included in the request all existing drafts are returned in the set of results. |
| POST /ppr/api/v1/drafts | Create a new draft of a Financing Statement or an Amendment/Court Order Statement. |
| GET /ppr/api/v1/drafts/{document_id} | Retrieve an existing draft of the Financing Statement or Amendment/Court Order Statement that matches the document ID. |
| PUT /ppr/api/v1/drafts/{document_id} | Update an existing draft of a Financing Statement or Amendment/Court Order Statement. |
| DELETE /ppr/api/v1/drafts/{document_id} | Delete an existing draft of the Financing Statement or Amendment/Court Order Statement that matches the document ID. |
| GET /ppr/api/v1/financing-statements | Retrieve a list of Financing Statements created by the account ID submitting the request. As part of the search criteria, include a debtor name as request query parameters. BC Registries may apply restrictions still to be determined on what is included in the results. The startDateTime, endDateTime, and registrationType parameters may be used to refine the results. There is a limit on the number of items returned in the results (to be determined). The list of summary information includes the following properties:
|
| GET /ppr/api/v1/financing-statements/registrations | Retrieve a list of all Financing Statement registrations either created or added by the account ID submitting the request, sorted by most recent first. If no Financing Statements exist for the account and empty array is returned. Financing Statements that have expired or been discharged more than 30 days prior to the submission of the request, and registrations associated with such historical Financing Statements, are excluded from the results. Use the Add or Delete Account Registrations endpoints to add or remove registrations created with another account. |
| GET /ppr/api/v1/financing-statements/registrations/{registration_num} | Used by the PPR application to review summary information about a Financing Statement created by another account before adding it to the account list of registrations. |
| POST /ppr/api/v1/financing-statements/registrations/{registration_num} | Created for use by the PPR Application. Use this endpoint to add a Financing Statement created by another account to the List account Registrations results. Attempting to add a duplicate registration number returns a 409 Conflict status. Attempting to add registration number with restricted access returns a 403 Forbidden status. A registration number which does not exist, has expired, or has been discharged returns a 404 Not Found status. |
| DELETE /ppr/api/v1/financing-statements/registrations/{registration_num} | Remove a previously added Financing Statement registration created by another account from the list of registrations associated with the user account. |
| POST /ppr/api/v1/financing-statements | Create (register) a new Financing Statement. |
| GET /ppr/api/v1/financing-statements/{registration_num} | Retrieve by registration number a Financing Statement. The account ID used to submit the request must match the account ID used to create the Financing Statement identified by the registration number. |
| POST /ppr/api/v1/financing-statements/{registration_num}/amendments | Register a Financing Statement amendment or court order change as an Amendment Statement to add or delete:
|
| GET /ppr/api/v1/financing-statements/{registration_num}/amendments/{amendment_registration_num} | Retrieve by amendment registration number an Amendment Statement. The account ID used to submit the request must match the account ID used to create the Amendment Statement identified by the amendment registration number. The Amendment registration must be a change to the Financing Statement identified by the registration_num path parameter. |
| GET /ppr/api/v1/financing-statements/{registration_num}/changes/{change_registration_num} | Retrieve by change registration number a Change Statement. The account ID used to submit the request must match the account ID used to create the Change Statement identified by the change registration number. The Change registration must be a change to the Financing Statement identified by the registration_num path parameter. |
| GET /ppr/api/v1/financing-statements/{registration_num}/debtorNames | Retrieve by registration number a list of all debtor names associated with a Financing Statement. The account ID used to submit the request must match the account ID used to create the Financing Statement identified by the registration number. All existing debtor names are included in the response, including those for removed debtors. The list of names is sorted by the order they were submitted. Background: this endpoint is used by the PPR application to help the user identify a debtor for an amendment, change, discharge, or renewal registration. This extra piece of information helps prevent mistakes creating registrations on the wrong Financing Statement. |
| POST /ppr/api/v1/financing-statements/{registration_num}/discharges | Discharge a Financing Statement to remove a lien or encumbrance. Once discharged, a Financing Statement becomes historical and will not show up in search results. |
| GET /ppr/api/v1/financing-statements/{registration_num}/discharges/{discharge_registration_num} | Retrieve by discharge registration number a Discharge Statement. The account ID used to submit the request must match the account ID used to create the Discharge Statement identified by the discharge registration number. The Discharge registration must be a change to the Financing Statement identified by the registration_num path parameter. |
| POST /ppr/api/v1/financing-statements/{registration_num}/renewals | Renew a Financing Statement by extending the expiry date. Court order information is required and should only be included when submitting a renewal for a Repairer's Lien (RL) registration type. The Court Order Date must be between the base registration creation date and the request date. Specify lifeYears or lifeInfinite for all registration types except RL. Registrations with an infinite life cannot be renewed. A Debtor name is required as an additional check on the Financing Statement registration number. |
| GET /ppr/api/v1/financing-statements/{registration_num}/renewals/{renewal_registration_num} | Retrieve by renewal registration number a Renewal Statement. The account ID used to submit the request must match the account ID used to create the Renewal Statement identified by the renewal registration number. The Renewal registration must be a change to the Financing Statement identified by the registration_num path parameter. |
| GET /ppr/api/v1/party-codes/{code} | Find the name and address details by client code for a previously created re-usable Registering Party or Secured Party. |
| GET /ppr/api/v1/party-codes/accounts | Intended only to be used by the PPR application. Look up Secured Party codes associated with a user when creating or changing a Crown Charge Financing Statement registration. For Crown Charge registrations, the Secured Party must be a code selected from a restricted set. The response is an empty array if no matches are found. |
| GET /ppr/api/v1/party-codes/head-offices/{nameOrCode} | Use this endpoint to look up a party code for a registration Secured Party. You can then provide a party code instead of a name and address when submitting registration requests. This endpoint finds the party code, name and address details of all the branches that belong to a head office. Search either by business name or by head office code. A party code is a concatenation of head office and branch codes. A head office code may be between 0 (or 0000) and 9999. If the nameOrCode path parameter value is three or more characters long and all digits, the query is by code; otherwise it is by head office business name. The response is an empty array if no matches are found. |
| POST /ppr/api/v1/searches | Search Step 1 Executes a new search query as the first of two steps in the search process. The results are a summary list of one or more matches that after review can be filtered as the second step in the search process. The second step returns Financing Statement details. The optional startDateTime and endDateTime may be used to narrow the search. If the search returns no results, the HTTP response code is 422. A service fee is charged for each new search query. The six types of searches are:
|
| PUT /ppr/api/v1/searches/{searchId} | This operation is intended for BCRS application internal use only. It supports application search step 1 autosave of the search selection prior to the execution of search step 2. The added searchSummaryInformation "selected" property indicates if a query result is to be included in the search step 2 details. Note that this operation is a complete replacement of the search step 1 results. The response echoes back the request body.. |
| POST /ppr/api/v1/search-results/{searchId} | Search Step 2 As the second step in the search two-step process, choose from the summary information returned in the first step which Financing Statements to retrieve detailed information about. Only matchType and baseRegistrationNumber need to be provided to select a Financing Statement. The detail information includes all Change Statement, Amendment Statement, Renewal, and Discharge Statement information in chronological order. Exact match Financing Statements are automatically included in the results. If the request similar match "selected" property is either absent or set to true the associated Financing Statement is included in the response. |
| GET /ppr/api/v1/search-results/{searchId} | After a search has completed, this operation may be used to retrieve the search detail information identified by the searchId path parameter. |
| GET /ppr/api/v1/search-history | Retrieve a list of previous searches performed by the account ID submitting the request. The list items include the search criteria and summary results (search step 1 responses). The default sort order is by search timestamp starting with the most recent. The results size may be limited by number of items or by number of days in the past (for example, within the last 7 days). |
Date and Date Time Formats
All date-time property values are stored in the system as UTC timestamps. The API contains no date formatted properties: all dates (expiry, surrender, debtor birth, and court order) are formatted as date-time. All API responses represent date-time values in the UTC timezone.
| Type | Format | Examples |
|---|---|---|
| date-time | YYYY-MM-DDThh:mm:ss[Z|+|-hh:mm]. Either +hh:mm or -hh:mm (the time zone offset) or Z must be supplied. Default Z for Pacific time zone value. | 2021-01-14T21:08:32Z 2021-02-16T07:59:59+00:00 |
API Version History
| Date | Version | Description |
|---|---|---|
| 2020-08-28 | 1.0.0 | Initial version |
| 2021-03-30 | 1.0.0 | Updates from implementation. |
| 2021-03-30 | 1.0.0 | Change Date data type to DateTime for expiryDate, surrenderDate, debtor birthDate, and court order orderDate |
| 2021-03-30 | 1.0.0 | Search add endpoint to get account search history: 1. Add GET /ppr/api/v1/search-history 2. Update schema searchQueryResults: add exactResultsSize and selectedResultsSize. |
| 2021-03-30 | 1.0.0 | Search update search results detail: 1. Replace PUT /ppr/api/v1/searches/{searchId} with POST /ppr/api/v1/search-results/{searchId}. 2. Add support to format response data as a PDF: allow request header Accept=application/pdf. 3. Update response to include summary information with schema searchDetailResults. 4. Update financingStatementWithChanges schema: add matchType property. 5. Add GET /ppr/api/v1/searches/{searchId} to fetch previous search detail results (for a limited time). |
| 2021-03-30 | 1.0.0 | Search change POST /ppr/api/v1/searches no results response: Change the HTTP status response code to 201 (success) when no matches are found for the search criteria. The response does not include any results and totalResultsSize is 0. |
| 2021-03-30 | 1.0.0 | Search add endpoint to support UI autosave of search selection: 1. Update PUT /ppr/api/v1/searches/{searchId} 2. Update searchSummaryInformation schema: add "selected" property. |
| 2021-03-30 | 1.0.0 | Update Financing Statement schema: add registrationDescription, registrationAct, statusType, dischargeDateTime, courtOrderInformation. |
| 2021-03-30 | 1.0.0 | Update Renewal Statement schema: add lifeYears. |
| 2021-03-30 | 1.0.0 | Add GET, PATCH /ppr/api/v1/user-profile for maintaining user UI preferences. |
| 2021-04-09 | 1.0.0 | API Specification updates from search implementation. |
| 2021-05-13 | 1.0.0 | Add GET /ppr/api/v1/party-codes/head-offices/{nameOrCode} Update examples. |
| 2021-07-09 | 1.0.0 | Update search registration types add TA TG TM Update GET account financing statement list. New GET individual registration JSON and PDF: GET /ppr/api/v1/financing-statements/{registration_num}/amendments/{amendment_registration_num} GET /ppr/api/v1/financing-statements/{registration_num}/changes/{change_registration_num} GET /ppr/api/v1/financing-statements/{registration_num}/discharges/{discharge_registration_num} GET /ppr/api/v1/financing-statements/{registration_num}/renewals/{renewal_registration_num} New GET account registrations list. /ppr/api/v1/financing-statements/registrations Update examples. |
| 2021-08-20 | 1.0.0 | Add GET /api/v1/financing-statements/{registration_num}/debtorNames. Replace baseDebtor and baseDebtorName with debtorName. Add financingStatement.otherTypeDescription. |
| 2021-09-24 | 1.0.0 | Add POST /ppr/api/v1/financing-statements/registrations/{registration_num} Add DELETE /ppr/api/v1/financing-statements/registrations/{registration_num} Add GET /ppr/api/v1/party-codes/accounts Update change registration responses to return a verification statement. |
| 2021-10-12 | 1.0.0 | Add GET /ppr/api/v1/financing-statements/registrations/{registration_num} Remove create Change Registration, create and maintain a draft of a Change Registration. |
| 2021-10-22 | 1.0.0 | Add registrationsTable and miscellaneousPreferences to the UserProfile schema (expand PPR UI user preference settings). |
| 2021-11-02 | 1.0.0 | Add authorizationReceived to financingStatement, amendmentStatement, dischargeStatement, and renewalStatement schemas. |
| 2021-11-29 | 1.0.0 | Remove 4000 character limit on single general collateral description. Update vehicle collateral, general collateral and party descriptions. Remove general and vehicle collateral schema anyOf, allOf required conditions to resolve a gateway specification rendering issue. Add callbackURL request parameter to the /ppr/api/v1/search-results/{searchId} endpoint. |
| 2021-12-31 | 1.0.0 | Remove upper limit of 1000 on search results. Adjust individual and business debtor search algorithms. Fix search result report requests not working with partial selection data. |
| 2022-01-17 | 1.0.0 | Specification updates to renewalStatement and searchQuery schema descriptions. Fix Infinite Renewal report error. Allow secured party, debtor names with single quotation marks, commas. Change debtor business name search minimum length to 2 characters. Correct/change search result report Amendment Registration badges/labels: ADDED, AMENDED, DELETED, NAME CHANGED, ADDRESS CHANGED. Correct Amendment Registration conditional former name values. Correct Financing Statement consolidated view of amended general collateral: only include descriptionAdd and descriptionDelete together when adding 1 item and deleting 1 item. |
| 2022-01-19 | 1.0.0 | Specification updates to the vehicleCollateral schema definition: remove EV; do not allow AP with new registrations. |
| 2022-02-22 | 1.0.0 Patch | Handle search result reports with few results but a large data size (large number of serial collateral). Generate the report as part of Search Step 2, return an ACCEPTED response, retrieve the report with a subsequent GET. |
| 2022-03-10 | 1.0.0 Patch | Add query parameters to GET /ppr/api/v1/financing-statements/registrations to filter results. Filter by clientReferenceId, registrationNumber, or startDateTime and endDateTime. Use to check the status of specific account registrations. |
| 2022-07-14 | 1.0.0 Patch | Add crown charge registrations type TO (TOBACCO TAX ACT) and SV (SPECULATION AND VACANCY TAX ACT). |
| 2023-01-05 | 1.0.9 Patch | Re-organize large search result report with more than 700 registrations into sub-reports to improve performance. |
| 2023-03-23 | 1.1.2 Patch | Add three transition related properties to the financingStatement model. Transition registrations are active registrations which were re-registered in the electronic registry. If the financing statement is for one of these registrations, three additional properties are conditionally included in a response: transitionDescription, transitionDate, and transitionNumber. |
| 2024-06-15 | 1.2.5 Patch | Accept callback URLs for search result report requests where the number of results is small but the JSON data size is large (over 220KB). Add support for the Securities Act Commision new registration type SE - SECURITIES ORDER OR PROCEEDINGS NOTICE. Creating, amending, and discharging this registration type is restricted to the Securities Act Commission account ID. The following updates were made for this new registration type, which may be included in search results:
|
Additional Resources
- Refer to the BC Gov site to answer any PPR business rule related questions including Fees.
- Download a Demo Postman collection to view at least one example of each API path. Provide your own API key and account Id to submit requests and view the responses.
- Download a Glossary of Terms
- View the API specification property lengths by model/schema name. Note that the definitions are not final.
Page History
Updates of note to this page are recorded here.
| Date | Description |
|---|---|
| 2020-11-09 | Update Postman collection. |
| 2021-04-09 | Update Postman collection. |
| 2021-11-05 | Update Postman collection. |
| 2021-12-31 | Update API specification property lengths. Add Large Search Reports section. |
| 2022-03-10 | Add section Reports for Registrations With a Large Data Size. |
| 2022-05-02 | Update API specification vehicleCollateral model/schema description regarding required properties. |
| 2024-06-15 | Update section Reports for Registrations With a Large Data Size to add callback URL information. |