AlbertaJobcentre.ca API

Jobs

Job Instance

Represents a single job instance.

URI

https://www.albertajobcentre.ca/api/v1.1/jobs/{id}

Properties

Property Type Description
id Int32 Unique identifier of the job.
referenceId String (max 50) Employer's unique identifier of the job. If one is not provided by the employer, this value is empty string.
employer Object The employer to which this job belongs. This object has the following properties:
Property Type Description
id Int32 Unique identifier of the employer.
name String (max 128) Employer name.
title String (max 256) Title of the job.
publishDate Date (ISO 8601) The date the job was published.
closeDate Date (ISO 8601) The date the job will close.
confidential Boolean true if the employer name is confidential, false if the employer name is not confidential.
autoRefresh Boolean true if auto-refresh is enabled for the job. Auto-refresh will automatically refresh the publish date every 7 days.
This is only applicable for employers on unlimited job plans
status String (max 10) The current status of the job. Possible values:
  • active
  • archived
  • draft
locations Array of Objects Each object contains the following properties.
See Locations for full details.
Property Type Description
id Int32 Unique identifier of the location.
name String (max 256) Human readable name for the location.
description String (max 300) Human readable description for the location.
type String (max 50) The type of location.
categories Array of Objects Each object contains the following properties.
See Job Categories for a full list.
Property Type Description
id Int32 Unique identifier of the job category.
name String (max 40) Human readable name for the job category.
positionType Object Position type of the job.
See Position Types for a full list.
Property Type Description
id Int32 Unique identifier of the position type.
name String (max 10) Human readable name for the position type.
salary Object Salary for the job.
Note: if salary is not defined, this will be null
Property Type Description
amount Decimal Base salary.
maxAmount Decimal Optional max salary.
period Object
Property Type Description
id Int32 Unique identifier of the salary period. Possible values are:
  • 1: Yearly
  • 2: Monthly
  • 3: Weekly
  • 4: Daily
  • 5: Hourly
name String (max 50) Human readable name for the salary period.
unit String (max 50) Unit of measure for salary period
plusCommission Boolean true if job earns commission.

The default is false.
description String HTML formatted job description.
applicantRoutingType Object Object with the following properties:
Property Type Description
id Int32 Unique identifier of the applicant routing type. Possible values are:
  • 1: Email (i.e. applications are collected by AlbertaJobcentre.ca and emailed to employer)
  • 2: URL (i.e. candidates are directed to employer's website to apply)
name String (max 50) Human readable name for the applicant routing type.
applicationEmail String (max 50) Email address where a copy of the job application will be sent. Only applicable when the applicant routing type is Email.
applicationUrl String (max 200) URL where candidates will be directed to apply for the job. Only applicable when the applicant routing type is URL.

HTTP GET

Authentication: Required

Example

Request

https://www.albertajobcentre.ca/api/v1.1/jobs/183668

Response
{
    "applicantRoutingType":{
        "id":1,
        "name":"Email"
    },
    "status":"active",
    "employer":{
        "id":72,
        "name":"Pure Media Designs"
    },
    "referenceId":null,
    "applicationUrl":null,
    "id":183668,
    "title":"Account Manager",
    "locations":[
        {"id":156,"description":"Vancouver, BC","name":"Vancouver","type":"Town"},
        {"id":405,"description":"Whistler, BC","name":"Whistler","type":"Town"}
    ],
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "positionType":{
        "id":1,
        "name":"Full Time"
    },
    "categories":[
        {"id":1,"name":"Account Management"},
        {"id":2,"name":"Sales & Marketing"}
    ],
    "salary": {
        "amount": 90000.00,
        "maxAmount": null,
        "period": {
            "id": 1,
            "name": "Yearly",
            "unit": "year"
        },
        "plusCommission": false
    },
"applicationEmail":"johnny@email.com",
    "publishDate":"2018-03-28",
    "closeDate":"2018-05-27",
    "autoRefresh": false,
    "confidential":false
}

HTTP POST

HTTP POST allows you to create a new job. The JSON format expected from HTTP POST is symmetrical with the result returned from GET. For example, if you take the object returned from GET, remove the id and referenceId properties and POST it back, you will create a new job with the same property values.

Authentication: Required

Parameters

Property Type Required? Description
referenceId String (max 50) Company's unique identifier of the job.
If you have a referenceId, we recommend that you use HTTP PUT instead, because HTTP PUT is idempotent (i.e. multiple requests puts the server into the same state). POSTing the same referenceId multiple times will reject the request after the first time.
title String (max 256) ✓
closeDate Date (ISO 8601) The date that the job should close.
The publishDate will be set automatically by the API and is read-only, but the closeDate can be set explicity.
If a closeDate is not provided, it will be set to 60 days after the publishDate.
confidential Boolean true if the employer name is confidential. false if the employer name is not confidential.

The default is false.
autoRefresh Boolean true to enable auto-refresh. false to disable auto-refresh. Auto-refresh will automatically refresh the publish date every 7 days.

The default is false and is only applicable for employers on unlimited job plans.
status String (max 10) The status of the job. The following values are accepted:
  • active
  • archived
  • draft
The default is draft.
locations:[{description}] Array of Objects ✓ An array of location objects. At least one is required and up to three is allowed.
See Locations for more info.

To include a location, set the description property in one of two ways:
  1. City only (e.g. Vancouver)
  2. City, ProvinceCode (e.g. Vancouver, BC)
To avoid ambiguity, we recommend that you include both City and ProvinceCode.

Example: 
"locations":[
    {"description":"Vancouver, BC"},
    {"description":"Whistler, BC"}
]
Note: Even if the location is not currently in our system (as found through our Locations end point, if you send a valid Canadian location, it will be accepted.
categories:[{id}] Int32 ✓ An array of job category objects. At least one is required and up to three is allowed.
See Job Categories for a full list.

Example: 
"categories":[
    {"id":7},
    {"id":9}
]
positionType.id Int32 ✓ The position type of the job.
See Position Types for a full list.
salary.amount Decimal Base salary amount.
salary.maxAmount Decimal Max salary amount.
salary.period.id Int32 ✓* Unique identifier of the salary period. Possible values:
  • 1: Yearly
  • 2: Monthly
  • 3: Weekly
  • 4: Daily
  • 5: Hourly
*This property is required if salary.amount is specified.
salary.plusCommission Boolean true if job earns commission.

The default is false.
description String ✓ The job description in HTML format.
Technically there is no limitation on the length of the job description, but practically we would like you to keep this length to within reason so that candidates can easily consume it.
The following tags are allowed:

strong, b, em, i, br, p, div, ul, ol, li, a

HTML attributes:
  • For anchor tags (i.e. 'a'), href attribute must exist and target attribute is optional. All other attributes are not allowed.
  • For all other tags, attributes are not allowed.
applicantRoutingType.id Int32 ✓ Unique identifier of the applicant routing type. Possible values:
  • 1: Email (i.e. applications are collected by AlbertaJobcentre.ca and emailed to employer)
  • 2: URL (i.e. candidates are directed to employer's website to apply)
applicationEmail String (max 50) ✓* Email address where a copy of the job application will be sent.
*This property is required if applicantRoutingType.id is 1.
applicationUrl String (max 200) ✓* URL (including http:// or https://) where candidates will be directed to apply for the job.
*This property is required if applicantRoutingType.id is 2.

Example 1

Create a new job:

  • without a referenceId
  • without a closeDate
  • where applications should be collected by AlbertaJobcentre.ca and emailed to johnny@email.com
Request
POST https://www.albertajobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 471
        
{
    "title":"Account Manager",
    "status":"active",
    "locations":[
        {"description":"Vancouver, BC"},
        {"description":"Whistler, BC"}
    ],
    "categories":[
        {"id":7},
        {"id":9}
    ],
    "positionType":{
        "id":1
    },
    "salary": {
        "amount": 90000.00,
        "maxAmount": 110000.00,
        "period": {
            "id": 1
        },
        "plusCommission": true
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "applicantRoutingType":{
        "id":1
    },
    "applicationEmail":"johnny@email.com"
}
Response
HTTP/1.1 201 Created
Content-Length: 665
Content-Type: application/json
Location: https://www.albertajobcentre.ca/api/v1.1/jobs/183668

{
    "applicationEmail":"johnny@email.com",
    "applicantRoutingType":{
        "name":"Email",
        "id":1
    },
    "positionType":{
        "name":"Full Time",
        "id":1
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "employer":{
        "name":"Pure Media Designs",
        "id":72
    },
    "publishDate":"2018-04-02",
    "closeDate":"2018-06-01",
    "status":"active",
    "locations":[
        {"name":"Vancouver","description":"Vancouver, BC","id":156,"type":"Town"},
        {"name":"Whistler","description":"Whistler, BC","id":405,"type":"Town"}
    ],
    "applicationUrl":null,
    "confidential":false,
    "autoRefresh": false,
    "id":183668,
    "salary": {
        "amount": 90000.0000,
        "maxAmount": 110000.0000,
        "period": {
            "id": 1,
            "name": "Yearly",
            "unit": "year"
        },
        "plusCommission": true
    },
    "categories":[
        {"name":"Account Management","id":7},
        {"name":"Sales & Marketing","id":9}
    ],
"referenceId":null,
    "title":"Account Manager"
}

Example 2

Create a new job:

  • with a referenceId
  • with a closeDate
  • where applicants should be sent to employer's website

Note: in this scenario where you have a referenceId, we recommend that you use HTTP PUT instead of HTTP POST, as HTTP PUT is idempotent (i.e. multiple requests puts the server into the same state). You can use HTTP PUT to both create and modify a job without worry. On the other hand, POSTing the same referenceId multiple times will reject the request after the first time.

Request
POST https://www.albertajobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 519

{
    "referenceId":"job-001",
    "title":"Account Manager",
    "status":"active",
    "locations":[
        {"description":"Vancouver, BC"},
        {"description":"Whistler, BC"}
    ],
    "closeDate":"2018-04-20",
    "categories":[
        {"id":7},
        {"id":9}
    ],
"positionType":{
        "id":1
    },
    "salary": {
        "amount": 90000.00,
        "maxAmount": 110000.00,
        "period": {
            "id": 1
        },
        "plusCommission": true
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "applicantRoutingType":{
        "id":2
    },
    "applicationUrl":"http://www.company.com/job001"
}
Response
HTTP/1.1 201 Created
Content-Length: 697
Content-Type: application/json
Location: https://www.albertajobcentre.ca/api/v1.1/jobs/183668

{
    "applicationEmail":null,
    "applicantRoutingType":{
        "name":"URL",
        "id":2
    },
    "positionType":{
        "name":"Full Time",
        "id":1
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "employer":{
        "name":"Pure Media Designs",
        "id":72
    },
    "publishDate":"2018-04-03",
    "closeDate":"2018-04-20",
    "status":"active",
    "locations":[
        {"name":"Vancouver","description":"Vancouver, BC","id":156,"type":"Town"},
        {"name":"Whistler","description":"Whistler, BC","id":405,"type":"Town"}
    ],
    "applicationUrl":"http:\/\/www.company.com\/job001",
    "confidential":false,
    "autoRefresh": false,
    "id":202054,
    "salary": {
        "amount": 90000.0000,
        "maxAmount": 110000.0000,
        "period": {
            "id": 1,
            "name": "Yearly",
            "unit": "year"
        },
        "plusCommission": true
    },
    "categories":[
        {"name":"Account Management","id":7},
        {"name":"Sales & Marketing","id":9}
    ],
"referenceId":"job-001",
    "title":"Account Manager"
}

HTTP PUT

HTTP PUT allows you to create a new job (with a referenceId) or update an existing job. The JSON format expected from HTTP PUT is symmetrical with the result returned from GET. For example, if you take the object returned from GET, change a few properties and PUT it back to the server, your request will succeed.

When modifying a job with HTTP PUT, we treat your request more like HTTP PATCH than a true HTTP PUT. This means that we support partial updates. For example, if you just want to modify the job title, you can just send the title {"title":"Updated Job Title"} instead of sending the whole object graph.

Authentication: Required

Parameters

The parameters are the same as HTTP POST.

Job Identification

There are 2 mechanisms that you can use to identify a job:

  • AlbertaJobcentre.ca's unique job id, which is passed in the URI.
    Example:
    https://www.albertajobcentre.ca/api/v1.1/jobs/183668
  • referenceId, which is passed as a JSON property in the body of the request.
    Example:
    {"referenceId":"job-001"}

Example 1

Create a new job with referenceId.

Creating a new job using referenceId is the exact same as Example 2 in HTTP POST, except that you will change the method to PUT.

Example 2

Modify a job with job id.

Request
PUT https://www.albertajobcentre.ca/api/v1.1/jobs/183668 HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 471

{
    "title":"Account Manager",
    "status":"active",
    "locations":[
        {"description":"Vancouver, BC"},
        {"description":"Whistler, BC"}
    ],
    "categories":[
        {"id":7},
        {"id":9}
    ],
"positionType":{
        "id":1
    },
    "salary": {
        "amount": 90000.00,
        "maxAmount": 110000.00,
        "period": {
            "id": 1
        },
        "plusCommission": true
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "applicantRoutingType":{
        "id":1
    },
    "applicationEmail":"johnny@email.com"
}
Response
HTTP/1.1 200 OK
Content-Length: 666
Content-Type: application/json

{
    "applicationEmail":"johnny@email.com",
    "applicantRoutingType":{
        "name":"Email",
        "id":1
    },
    "positionType":{
        "name":"Full Time",
        "id":1
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "employer":{
        "name":"Pure Media Designs",
        "id":72
    },
    "publishDate":"2018-03-28",
    "closeDate":"2018-05-27",
    "status":"active",
    "locations":[
        {"name":"Vancouver","description":"Vancouver, BC","id":156,"type":"Town"},
        {"name":"Whistler","description":"Whistler, BC","id":405,"type":"Town"}
    ],
    "applicationUrl":null,
    "confidential":false,
    "autoRefresh": false,
    "id":183668,
    "salary": {
        "amount": 90000.0000,
        "maxAmount": 110000.0000,
        "period": {
            "id": 1,
            "name": "Yearly",
            "unit": "year"
        },
        "plusCommission": true
    },
    "categories":[
        {"name":"Account Management","id":7},
        {"name":"Sales & Marketing","id":9}
    ],
"referenceId":null,
    "title":"Account Manager"
}

Example 3

Modify a job with referenceId.

Note: job id is no longer required, but referenceId is now required to identify the resource.

Request
PUT https://www.albertajobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 501

{
    "referenceId":"job-001",
    "title":"Account Manager",
    "status":"active",
    "locations":[
        {"description":"Vancouver, BC"},
        {"description":"Whistler, BC"}
    ],
    "categories":[
        {"id":7},
        {"id":9}
    ],
"positionType":{
        "id":1
    },
    "salary": {
        "amount": 90000.00,
        "maxAmount": 110000.00,
        "period": {
            "id": 1
        },
        "plusCommission": true
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "applicantRoutingType":{
        "id":1
    },
    "applicationEmail":"johnny@email.com"
}
Response
HTTP/1.1 200 OK
Content-Length: 694
Content-Type: application/json

{
    "applicationEmail":"johnny@email.com",
    "applicantRoutingType":{
        "name":"Email",
        "id":1
    },
    "positionType":{
        "name":"Full Time",
        "id":1
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "employer":{
        "name":"Pure Media Designs",
        "id":72
    },
    "publishDate":"2018-04-03",
    "closeDate":"2018-06-02",
    "status":"active",
    "locations":[
        {"name":"Vancouver","description":"Vancouver, BC","id":156,"type":"Town"},
        {"name":"Whistler","description":"Whistler, BC","id":405,"type":"Town"}
    ],
    "applicationUrl":null,
    "confidential":false,
    "autoRefresh": false,
    "id":202046,
    "salary": {
        "amount": 90000.0000,
        "maxAmount": 110000.0000,
        "period": {
            "id": 1,
            "name": "Yearly",
            "unit": "year"
        },
        "plusCommission": true
    },
    "categories":[
        {"name":"Account Management","id":7},
        {"name":"Sales & Marketing","id":9}
    ],
"referenceId":"job-001",
    "title":"Account Manager"
}

Example 4

Archive a job with job id.

Request
PUT https://www.albertajobcentre.ca/api/v1.1/jobs/183668 HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 29

{
    "status":"archived"
}
Response
HTTP/1.1 200 OK
Content-Length: 668
Content-Type: application/json

{
    "applicationEmail":"johnny@email.com",
    "applicantRoutingType":{
        "name":"Email",
        "id":1
    },
    "positionType":{
        "name":"Full Time",
        "id":1
    },
    "description":"<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>",
    "employer":{
        "name":"Pure Media Designs",
        "id":72
    },
    "publishDate":"2018-04-03",
    "closeDate":"2018-06-02",
    "status":"archived",
    "locations":[
        {"name":"Vancouver","description":"Vancouver, BC","id":156,"type":"Town"},
        {"name":"Whistler","description":"Whistler, BC","id":405,"type":"Town"}
    ],
    "applicationUrl":null,
    "confidential":false,
    "autoRefresh": false,
    "id":183668,
    "salary": {
        "amount": 90000.0000,
        "maxAmount": 110000.0000,
        "period": {
            "id": 1,
            "name": "Yearly",
            "unit": "year"
        },
        "plusCommission": true
    },
    "categories":[
        {"name":"Account Management","id":7},
        {"name":"Sales & Marketing","id":9}
    ],
"referenceId":null,
    "title":"Account Manager"
}

Example 5

Archive a job with referenceId.

Request
PUT https://www.albertajobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 59

{
    "referenceId":"job-001",
    "status":"archived"
}
Response
Response is similar to Example 4.

Example 6

Publish an archived job with job id.

Request
PUT https://www.albertajobcentre.ca/api/v1.1/jobs/183668 HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 27

{
    "status":"active"
}
Response
Response is similar to Example 4.

HTTP DELETE

HTTP DELETE allows you to delete a job.

Job Identification

There are 2 mechanisms that you can use to identify a job:

  • AlbertaJobcentre.ca's unique job id, which is passed in the URI.
    Example:
    https://www.albertajobcentre.ca/api/v1.1/jobs/183668
  • referenceId, which is passed as a JSON property in the body of the request.
    Example:
    {"referenceId":"job-001"}

Example 1

Delete a job with job id.

Request
DELETE https://www.albertajobcentre.ca/api/v1.1/jobs/183668 HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 0
Response
HTTP/1.1 204 No Content

Example 2

Delete a job with referenceId.

Request
DELETE https://www.albertajobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.albertajobcentre.ca
API-Key: 932d2608-2e18-41f7-bf24-caa922ee9d23
Content-Type: application/json; charset=UTF-8
Content-Length: 31

{
  "referenceId":"job-001"
}
Response
HTTP/1.1 204 No Content

Jobs List

Represents a list of job headers.

URI

https://www.albertajobcentre.ca/api/v1.1/jobs

Properties

This API returns job headers, which is a subset of jobs. The available properties are listed below, but the type and description are ommitted because they are identical to the properties of a job and is described above.

  • id
  • referenceId
  • employer
  • title
  • publishDate
  • locations
  • confidential
  • status

HTTP GET

Returns a list of job headers for the authenticated employer. The list includes paging information and is sorted by publishDate in descending order.

Authentication: Required


Query String

Paramter Type Required? Description
q String No Job query term. This will match job title and referenceId. If this parameter is ommitted, then jobs will not be filtered by term.
status String No Pass in a status to filter the list to only include jobs with the specified status. Possible values are:
  • active
  • archived
  • draft
If this parameter is ommitted, then jobs with all statuses will be returned.
pageSize Int32 No Specifies the number of records to return at a time. The default is 10 and the maximum is 100.
page Int32 No Specifies which page to return. The default is 1.

Example 1

Request all job headers for the authenticated employer.

Request

https://www.albertajobcentre.ca/api/v1.1/jobs

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

{
    "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":"2018-03-28",
            "confidential":false,
            "status":"active"
        },
        ...
    ],
    "paging":{
        "total":25,
        "previous":null,
        "page":1,
        "pages":3,
        "next":"https://www.albertajobcentre.ca/api/v1.1/jobs?pageSize=10&page=2",
        "pageSize":10
    }
}

Example 2

Request active job headers for the authenticated employer with page size of 20.

Request

https://www.albertajobcentre.ca/api/v1.1/jobs?status=active&pageSize=20

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

{
    "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":"2018-03-28",
            "confidential":false,
            "status":"active"
        },
        ...
    ],
    "paging":{
        "total":21,
        "previous":null,
        "page":1,
        "pages":2,
        "next":"https://www.albertajobcentre.ca/api/v1.1/jobs?status=active&pageSize=20&page=2",
        "pageSize":20
    }
}