BCjobs.ca API

Response Formats

Our API responds with a JSON serialized object in the body. Any exceptions to this will be noted below.

Success Response Status Codes

Status Code Name Description
200 OK

Standard response for successful requests.

Example:

HTTP/1.1 200 OK
Content-Length: 27
Content-Type: application/json

{"id":1,"name":"Full Time"}
201 Created

The request was fulfilled and resulted in a new resource being created. An HTTP Location header is included in the response.

Example:

HTTP/1.1 201 Created
Content-Length: 665
Content-Type: application/json
Location: https://www.bcjobs.ca/api/v1.1/jobs/183668

{
    "id":183668,
    "title":"Account Manager",
    ...
}
204 No Content

Resource was successfully deleted.

Example:

HTTP/1.1 204 No Content

Success Response Body

With the exception of 204 status (which doesn't contain a response body), all success responses will contain a JSON serialized object.

Single Object Instance

When returning a single object (e.g. a PositionType), the response body will contain a JSON serialized object graph.

Example:

{
    "id":1,
    "name":"Full Time"
}

List

When returning a list, an array of objects will be wrapped in a data property.

Example:

{
    "data":[
        {"id":1,"name":"Full Time"},
        {"id":2,"name":"Part Time"},
        {"id":3,"name":"Contract"},
        {"id":4,"name":"Temp"},
        {"id":5,"name":"Volunteer"}
    ]
}

Paging Information for Long Lists

If lists are long, the API returns partial results in a single page. The representation includes a paging object with the following properties:

Property Type Description
total Int32 Total number of records available.
pageSize Int32 The size of a page.
page Int32 The current page.
pages Int32 Total number of pages.
previous String URI to the previous page if it exists. If it doesn't exist, this will be empty string.
next String URI to the next page if it exists. If it doesn't exist, this will be empty string.

Example:

{
    "data":[
        {
            "id":183668,
            "title":"Account Manager",
            "locations":[
                {"id":156,"description":"Vancouver, BC","name":"Vancouver","type":"Town"},
                {"id":405,"description":"Whistler, BC","name":"Whistler","type":"Town"}
            ],
            "employer":{
                "id":72,
                "name":"Pure Media Designs"
            },
            "referenceId":null,
            "publishDate":"2013-03-28",
            "confidential":false,
            "status":"active"
        },
        ...
    ],
    "paging":{
        "total":25,
        "previous":null,
        "page":1,
        "pages":3,
        "next":"https://www.bcjobs.ca/jobs?pageSize=10&page=2",
        "pageSize":10
    }
}

Error Response Status Codes

Status Code Name Description
400 Bad Request

The request was invalid. Please review the message and try again.

Example:

HTTP/1.1 400 Bad Request
Content-Length: 60
Content-Type: application/json

{"message":"Email is invalid.","type":"ValidationException"}
401 Unauthorized

Not authorized to make the request.

Example:

HTTP/1.1 401 Unauthorized
Content-Length: 123
Content-Type: application/json

{"message":"Not authorized to access job: 202038","type":"UnauthorizedAccessException"}
403 Forbidden

Attempted to perform an operation that is forbidden.

Example:

HTTP/1.1 403 Forbidden
Content-Length: 65
Content-Type: application/json

{"message":"Insufficient job post credit.","type":"InsufficientCreditException"}
404 Not Found

Resource was not found.

Example:

HTTP/1.1 404 Not Found
Content-Length: 65
Content-Type: application/json

{"message":"Job ID 183668 not found.","type":"NotFoundException"}

404 responses can also return plain text. When it does, there's a known issue where the Content-Type header still declares application/json when it should be text/plain.

Example:

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 9

Not Found
405 Method Not Allowed

The method (aka verb) used is not allowed.

405 responses return plain text instead of JSON.

Example:

HTTP/1.1 405 Method Not Allowed
Content-Type: text/plain
Content-Length: 18

Method Not Allowed
500 Internal Server Error

An unexpected error occurred on the server.

Example:

HTTP/1.1 500 Internal Server Error
Content-Length: 52
Content-Type: application/json

{"message":"Argument is undefined."}
503 Service Unavailable

Server is undergoing maintenance and is not available.

503 responses return HTML instead of JSON.

Error Response Body

When the error response returns JSON, the following properties will be available.

Property Always Available Description
message ✓ Error message.
type

Type of error will be one of the following:

Type Status Code Description
ArgumentException 400 Tried to pass and argument that is invalid.
InsufficientCreditException 403 Insufficient credit to perform the operation.
InvalidCredentialsException 401 Authentication failed.
InvalidOperationException 400 Tried to perform an operation that is invalid. Refer to message property for more info.
PaymentException 400 Payment was declined.
UnauthorizedAccessException 401 User is not authorized to make the request.
ValidationException 400 Failed validation. Refer to message property for more info.

Example:

{
    "message":"Email is invalid.",
    "type":"ValidationException"
}

Data Formats

Dates & Times

All dates and times in requests and responses are represented in Pacific time in ISO 8601 format. Dates without a time part will look like this:

2013-03-25

Dates with a time part will look like this:

2013-03-25T13:00