Jobs

Job Instance

Represents a single job instance.

URI

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

Properties

Property

Type

Description

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.

HTTP GET

Authentication: Required

Example

Request

https://www.ytjobcentre.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: City only (e.g. Vancouver) 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 YTjobcentre.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 YTjobcentre.ca and emailed to johnny@email.com

Request

POST https://www.ytjobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.ytjobcentre.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.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.ytjobcentre.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.ytjobcentre.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:

YTjobcentre.ca's unique job id, which is passed in the URI.
Example:
https://www.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs/183668 HTTP/1.1
Host: www.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs/183668 HTTP/1.1
Host: www.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs/183668 HTTP/1.1
Host: www.ytjobcentre.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:

YTjobcentre.ca's unique job id, which is passed in the URI.
Example:
https://www.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs/183668 HTTP/1.1
Host: www.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs HTTP/1.1
Host: www.ytjobcentre.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.ytjobcentre.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.ytjobcentre.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.ytjobcentre.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.ytjobcentre.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.ytjobcentre.ca/api/v1.1/jobs?status=active&pageSize=20&page=2",
        "pageSize":20
    }
}