This section details how to create, update and delete Job adverts in the Kudoz system.

Please refer to the authentication and common errors to have a better understanding of (resp.) authentication and error management in the Kudoz API.

Create Job

Route

POST /jobs

Parameters

Parameter Description
reference
required
Job’s reference in the client(your) system
title
required
Title of the job ad
organization_name
required
The organization where the job is proposed
organization_type
optional
The organization type for this offer. See organization type constants.
company_description
required
Any relevant description of the company (location, perks, culture etc.)
job_description
required
The description of the actual job
apply_email
optional
An email address where candidate applications will be sent. This feature is not available by default. Please liaise with support for more information.
contract_id
required
See contract constants
salary_id
required
See salary constants
salary_text
required
The salary that will be shown to the candidate
industry_id
required
See industry constants
department_id
required
See department constants
seniority
required
Required minimum number of years of experience
education
required
Required number of years of post high-school education
skills
optional
An array of required skills. Example: ["marketing","facebook ads","community management"]
question
optional
An optional question for the candidate during his/her application process. Example: What makes you special?.
start_date
optional
When the advertised position is available. Example: 2017-02-01.
location
required
See Location object below.
recruiter
required
See Recruiter object below.

Location

Geographical location of the Job.

Parameter Description
country
required
Country Alpha 2 code according to the ISO 3166-1 standard. Example: FR for France.
city
required
City name. Examples: Paris, Reykjavik, London.
state
optional
State where the city is located. Mandatory if country is US, CA or MX. Example: California.

Recruiter

Description of the recruiter posting the job ad. Might be different from the company where the position is to be provided.

Parameter Description
email
required
Recruiter’s email address
phone
optional
Recruiter’s phone number
organization_name
optional
Recruiter’s organization name (might be different from the above job organization_name)
organization_type
optional
Recruiter’s organization type. See organization type constants.
first_name
optional
Recruiter’s first name if applicable
last_name
optional
Recruiter’s last name if applicable

Responses

On Success

A HTTP status code 201 with an empty body.

On Failure

See common errors.

Example

URL:

POST /jobs

Payload:

{
  "reference": "AM-1234",
  "title": "Account Manager",
  "organization_name": "Acme Corp.",
  "company_description": "Acme Corp was founded in 1881 by Jean-Louis Acme, ...",
  "job_description": "As an account manager, you will be in charge of ...",
  "apply_email": "talents@acmecorp.com",
  "contract_id": 1,
  "salary_id": 2,
  "salary_text": ">€40K - Provides Equity",
  "industry_id": 12,
  "department_id": 6,
  "seniority": 3,
  "education": 5,
  "skills": ["marketing","facebook ads","community management"],
  "location": {
    "city": "Paris",
    "country": "FR"
  },
  "recruiter": {
    "email": "recruiter_1234@example.com",
    "phone": "33643124789",
    "organization_name": "Headhunters Inc.",
    "first_name": "Jack",
    "last_name": "Bauer"
  }
}

Response:

HTTP status code 201 with an empty body.

Update Job

Route

PUT /jobs/:reference

Parameters

Any subset of the parameters detailed in the create job parameters section above; except the job reference that remains immutable.

Responses

On Success

A HTTP status code 200 with an empty body.

On Failure

See common errors.

Example

URL:

PUT /jobs/AM-1234

Payload:

{
  "title": "Junior Account Manager",
  "salary_text": "Competitive - Provides Equity",
  "location": {
    "city": "Marseille",
    "country": "FR"
  },
  "recruiter": {
    "phone": "33643124790"
  }
}

Response:

HTTP status code 200 with an empty body.

Delete Job

Route

DELETE /jobs/:reference

Parameters

A valid job reference of a previously created job is required.

Responses

On Success

A HTTP status code 200 with an empty body.

On Failure

See common errors.

Example

URL:

DELETE /jobs/AM-1234

Payload:

empty

Response:

HTTP status code 200 with an empty body.