×


JOBS API

Postman Collection - https://documenter.getpostman.com/view/15829883/TzRYd4qR

Before using this API endpoint, you need a special token. Be sure to read our Terms & Guidelines to learn how the API may be used.



How to Post Jobs on We Work Remotely

The /remote-jobs endpoint allows you to post jobs to We Work Remotely. You can learn more about pricing for posting jobs here.

Before using this API endpoint, you need a special token. Please reach out to [email protected] if you would like to partner with WWR and post jobs via our API. Before doing so, be sure to read our Terms & Guidelines to learn how the API may be used.


Create a job

POST /remote-jobs

Parameters

NameTypeDescription
companystringRequired The name of the company the position is with.
titlestringRequired The title of the job position.
locationstringOptional Physical headquarters of the company itself (e.g. "Victoria, BC").
instructionsstringRequired An absolute URL to the application form of the job listing or email address.
descriptionstringRequired The full html description of the job (allowed tags: a ol ul li h1 h2 h3 p strong em br).
statusstringNote: to remove a job, change status to: canceled

Default: approved
emailstringRequired Job poster’s email address
category_idintegerRequired The category ID of the job.

One of: Design=1, Full-Stack Programming=2, Front-End Programming=17, Back-End Programming=18, Customer Support=7, Devops and Sysadmin=6, Sales and Marketing=9, Management and Finance=3, Product=11, All Other Remote=4
urlstringAbsolute URL of the company's website

Default: null
regionstringOptional The region of the job listing.

One of: Anywhere in the World, USA Only, North America Only, Latin America Only, Americas Only, Europe Only, UK Only, Canada Only, EMEA Only, Asia Only, Africa Only, Oceania Only, Other (don't specify)
company_biotextCompany's brief description (what they do).

Default: null
job_listing_typestringOptional Whether the job listing is Full-Time or Contract

One of: Full-Time or Contract.

Default: null
logoimageOptional The logo of the company. Note: The logo can be sent as an attachment or as a file of format PNG, JPEG or GIF

planstringOptional The plan of job listing

One of: standard, good, better or best.

Default: standard
partner_po_numberstringOptional The Purchase Order Number provided by the Partner

Default: null
salary_rangestringOptional The Salary Range of job listing

One of: Prefer not to share, $25,000 - $48,999 USD, $50,000 - $74,999 USD, $75,000 - $99,999 USD, $100,000 or more USD.

Default: null
skill_indexesarrayOptional Array of Skill IDs. Ex: [1, 2, 3]. Use Skills API to get all Skills

Default: null

Response

Status: 201 Created
{
  "id" : 8262,
  "company" : "Example Company",
  "url" : "https://example-company.com/",
  "title" : "Junior Web Developer",
  "category_id" : 2,
  "location" : "San Francisco, CA",
  "description" : "<h1>Example Job</h1><p>This job requires programming knowledge...</p>",
  "instructions" : "https://example.com/jobs/999999",
  "email" : "[email protected]",
  "status" : "approved",
  "region" : "USA Only",
  "company_bio" : "Your company or organization's bio (what they do).",
  "job_listing_type" : "Full-Time",
  "created_at" : "2020-01-11T17:20:15Z",
  "updated_at" : "2020-01-11T17:20:15Z",
  "expires_at" : "2020-02-11T17:20:15Z",
}

Update a job

PUT /remote-jobs/:id

Parameters

NameTypeDescription
companystringRequired The name of the company the position is with.
titlestringRequired The title of the job position.
locationstringOptional Physical headquarters of the company itself (e.g. "Victoria, BC").
instructionsstringRequired An absolute URL to the application form of the job listing or email address.
descriptionstringRequired The full html description of the job (allowed tags: a ol ul li h1 h2 h3 p strong em br).
statusstringNote: to remove a job, change status to: canceled

Default: approved
emailstringRequired Job poster’s email address
category_idintegerRequired The category ID of the job.

One of: Design=1, Full-Stack Programming=2, Front-End Programming=17, Back-End Programming=18, Customer Support=7, Devops and Sysadmin=6, Sales and Marketing=9, Management and Finance=3, Product=11, All Other Remote=4
urlstringAbsolute URL of the company's website

Default: null
regionstringOptional The region of the job listing.

One of: Anywhere in the World, USA Only, North America Only, Latin America OnlyAmericas Only, Europe Only, UK Only, Canada Only, EMEA Only, Asia Only, Africa Only, Oceania Only, Other (don't specify)
company_biotextCompany's brief description (what they do).

Default: null
job_listing_typestringOptional Whether the job listing is Full-Time or Contract

One of: Full-Time or Contract.

Default: null
logoimageOptional The logo of the company. Note: The logo can be sent as an attachment or as a file of format PNG, JPEG or GIF

planstringOptional The plan of job listing

One of: standard, good, better or best.

Default: standard
partner_po_numberstringOptional The Purchase Order Number provided by the Partner

Default: null
salary_rangestringOptional The Salary Range of job listing

One of: Prefer not to share, $25,000 - $48,999 USD, $50,000 - $74,999 USD, $75,000 - $99,999 USD, $100,000 or more USD.

Default: null
skill_indexesarrayOptional Array of Skill IDs. Ex: [1, 2, 3]. Use Skills API to get all Skills

Default: null

Response

Status: 200 OK
{
  "id" : 8262,
  "company" : "Example Company",
  "url" : "https://example-company.com/",
  "title" : "Junior Web Developer",
  "category_id" : 2,
  "location" : "San Francisco, CA",
  "description" : "<h1>Example Job</h1><p>This job requires programming knowledge...</p>",
  "instructions" : "https://example.com/jobs/999999",
  "email" : "[email protected]",
  "status" : "approved",
  "region" : "USA Only",
  "company_bio" : "Your company or organization's bio (what they do).",
  "job_listing_type" : "Whether your job listing is either Full-Time or Contract",
  "created_at" : "2020-01-11T17:20:15Z",
  "updated_at" : "2020-01-11T17:20:15Z",
  "expires_at" : "2020-02-11T17:20:15Z",
}

Show a job

GET /remote-jobs/:id
Status: 200 OK
{
  "id" : 8262,
  "company" : "Example Company",
  "url" : "https://example-company.com/",
  "title" : "Junior Web Developer",
  "category_id" : 2,
  "location" : "San Francisco, CA",
  "description" : "<h1>Example Job</h1><p>This job requires programming knowledge...</p>",
  "instructions" : "https://example.com/jobs/999999",
  "email" : "[email protected]",
  "status" : "approved",
  "region" : "USA Only",
  "company_bio" : "Your company or organization's bio (what they do).",
  "job_listing_type" : "Full-Time",
  "created_at" : "2020-01-11T17:20:15Z",
  "updated_at" : "2020-01-11T17:20:15Z",
  "expires_at" : "2020-02-11T17:20:15Z",
  "partner_po_number" : "006dc31c-ac31-41f6-a78a-be38bc1a8ae3",
  "salary_range" : "$25,000 - $48,999 USD"
}

All Skills

GET /remote-jobs/skills
Status: 200 OK

  [
    {
    "id" : 1,
    "name" : "A/B Testing",
    },
    {
    "id" : 2,
    "name" : "Ad Design",
    },
    {
    "id" : 3,
    "name" : "Adobe Creative Suite",
    }
    ....
  ]

Schema

All API access is over HTTPS, and accessed from the weworkremotely.com/api/v1/remote-jobs/ endpoint. All data is sent and received as JSON.

$ curl -i https://weworkremotely.com/api/v1/remote-jobs

HTTP/1.1 200 OK
Date: Thu, 13 Feb 2014 19:30:30 GMT
ETag: "def2bc69c674e5b48cd281aa12c2c8e9"
Server: cowboy
Status: 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

Timestamps

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Client Errors

There are two possible types of client errors on API calls that receive request bodies:

1. Sending invalid JSON.

Status: 400 Bad Request
{
  "message" : "Problem parsing JSON."
}

2. Sending invalid fields.

Status: 422 Unprocessable Entity
{
  "message" : "Validation failed.",
  "errors" : [
    {
      "attribute" : "body",
      "message" : "can't be blank"
    }
  ]
}

HTTP Verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.

VerbDescription
GETUsed for retrieving resources.
POSTUsed for creating resources.
PUTUsed for updating resources, or performing custom actions.
DELETEUsed for deleting resources.

Authentication

Auth Token (sent in a header)

$ curl -H "Authorization: Bearer AUTH_TOKEN" https://weworkremotely.com/api/v1/remote-jobs

Rate Limiting

For requests using Authentication, you can make up to 1,000 requests per day per authenticated user.

Once you go over the rate limit you will receive an error response:

HTTP/1.1 429 Too Many Requests
Status: 429 Too Many Requests

{ "message" : "You have exceeded your monthly request quota for this API. Please try again next month or contact [email protected] to increase your monthly quota limit." }

Staying within the rate limit

If you are exceeding your rate limit, you can likely fix the issue by caching API responses.


Conditional requests

Most responses return an ETag header. Many responses also return a Last-Modified header. You can use the values of these headers to make subsequent requests to those resources using the If-None-Match and If-Modified-Since headers, respectively. If the resource has not changed, the server will return a 304 Not Modified.

$ curl -i https://weworkremotely.com/api/v1/remote-jobs

HTTP/1.1 200 OK
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2014 17:10:33 GMT

$ curl -i https://weworkremotely.com/api/v1/remote-jobs -H 'If-None-Match: "e612e16d3c4d113573edb015d8eac1d5"'

HTTP/1.1 304 Not Modified
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2014 17:10:33 GMT

$ curl -i https://weworkremotely.com/api/v1/remote-jobs -H "If-Modified-Since: Sat, 22 Feb 2016 17:10:33 GMT"

HTTP/1.1 304 Not Modified
ETag: "e612e16d3c4d113573edb015d8eac1d5"
Status: 200 OK
Last-Modified: Sat, 22 Feb 2016 17:10:33 GMT

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests.

Here’s a sample request sent from a browser hitting http://example.com:

$ curl -i https://weworkremotely.com/api/v1/remote-jobs -H "Origin: http://example.com"

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Expose-Headers: ETag, Link
Access-Control-Allow-Credentials: true

This is what the CORS preflight request looks like:

$ curl -i https://weworkremotely.com/api/v1/remote-jobs -X OPTIONS -H "Origin: http://example.com" -H "Access-Control-Request-Method: GET"

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: OPTIONS, GET
Access-Control-Expose-Headers: ETag, Link
Access-Control-Max-Age: 1728000
Access-Control-Allow-Credentials: true

API Release Notes

Latest API Releases & Updates on We Work Remotely


  July 2021
  1. Addition of 2 new optional parameters in create a job API.
    (a) logo -  The logo of the company
    (b) plan -  The plan of job listing which is one of: standard, good, better or best. Default is set to standard.

  2. In 2021, We removed the Copywriting category and merged it with the Sales and Marketing category.

  May 2022
  1. Addition of a new optional parameter in create & update a job API.
    (a) partner_po_number - The Purchase Order Number provided by the Partner

  June 2022
  1. Addition of a new optional parameter in create & update a job API.
    (a) salary_range - The Salary Range of the job listing which is one of: Prefer not to share, $25,000 - $48,999 USD, $50,000 - $74,999 USD, $75,000 - $99,999 USD, $100,000 or more USD

  Sep 2022
  1. Addition of Skills API
  2. Addition of a new optional parameter in create & update a job API.
    (a) skill_indexes - The skills that apply to the listing. Array of Skill IDs. Ex: [1, 2, 3]

Check out our all product releases & improvements here.


Looking to Post a Job Via API?

Please reach out to [email protected] if you would like to partner with WWR and post jobs via our API.