API Information

This topic provides details of some of the conventions we have used within the API section.

  • We have used the <BaseURL> substitution string to represent the protocol and domain for your Passportal instance.

    • For example if your Passportal dashboard URL is https://instance.passportalmsp.com//dashboard#/default you would use https://instance.passportalmsp.com as your <BaseURL>.

    We have included an example below for the List Documents request of the <BaseURL> example and how the URL will actually be passed.

    • <BaseURL>/api/v2/documents
    • https://instance.passportalmsp.com/api/v2/documents
  • For each query we provide examples of using a cURL and Program for the API requests.
  • The cURL examples are based on Linux and macOS. If making cURL request from a Windows computer please ensure the requests are adapted to support the Windows environment. One example is to replace a single quotation mark ' with a double quotation mark ".

  • The API calls are also available in Swagger, accessed via https://<Base_URL>/api/documentation/v2/swagger.

API Error Messages

The system returns error messages where a problem was detected with the API request. We have included an example of some common errors below.

Code Description Example message
400 Invalid input or bad request {"success":false,"code":0,"status":400,"message":"invalid id"}
4XX Authorization issue { "success": "false", "message": "Invalid token: Malformed UTF-8 characters.", "code": 1006, "status": 401 }
{"success":false,"message":"Key verification failed","code":1000,"status":401}
403 Unauthorized { "success": "false", "message": "not found.", "code": 0, "status": 403 }
404 Invalid data { "success": "false", "message": "pageNum needs to be an integer between 1 and 9999.", "code": 0, "status": 404 }
405 Method issue {"success":false,"message":"Method not allowed","code":3000,"status":405}
500 Unexpected error { "success": "false", "message": "Unexpected error", "code": 0, "status": 500}

Where a malformed URL is used for the API request, for example <BaseURL>/apiv2documents/ instead of /api/v2/documents/, the request will return the HTML content of the "Whoops, looks like something went wrong" exception landing page.