NAV
shell

Introduction

Welcome Kit provides you a powerful API which gives you full control over most of your recruiting data.

For now, the Welcome Kit API can be used to:

In order to use the following endpoints, you will have to request an authentication token at contact@welcomekit.co.

Also, feel free to leave feedback, issues or features requests on the associated GitHub repository!

Authentication & Scopes

Example:

curl "WK_API_ENDPOINT_HERE"
  -H "Authorization: Bearer WK_API_KEY"

Make sure to replace WK_API_KEY with your API key.

Welcome Kit uses OAuth tokens to allow access to the API. We expect the OAuth token to be included in all API requests:

Authorization: Bearer WK_API_KEY

?access_token=WK_API_KEY

Also note that Welcome Kit uses OAuth scopes to protect its API endpoints.

Depending on the level of access you need, please ask us the required scopes from the list below:

Scope Description
me_r Read access on your personnal information
organizations_rw Read and Write access on your organization(s)
organizations_r Read access on your organization(s)
jobs_rw Read and Write access on your job offers
jobs_r Read access on your job offers
offices_rw Read and Write access on your offices
offices_r Read access on your offices
departments_rw Read and Write access on your departments
departments_r Read access on your departments
candidates_rw Read and Write access on your candidates
candidates_r Read access on your candidates

Jobs

Get jobs dependencies

curl -X GET "https://www.welcomekit.co/api/v1/external/jobs/dependencies" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"

The above command returns JSON structured like this:

{
  "contract_types": [
    {
      "id": "FULL_TIME",
        "name": {
          "en": "Full-Time",
          "fr": "CDI"
        }
    },
    {
      "id": "TEMPORARY",
      "name": {
        "en": "Temporary",
        "fr": "CDD / Temporaire"
      }
    },
    {
      "id": "INTERNSHIP",
      "name": {
        "en": "Internship",
        "fr": "Stage"
      }
    },
    ...
  ],
  "education_levels": [
    {
      "id": "NO_DIPLOMA",
      "name": {
        "en": "No Diploma",
        "fr": "Sans dipl\u00f4me"
      }
    },
    {
      "id": "CAP",
      "name": {
        "en": "Youth Training",
        "fr": "CAP"
      }
    },
    {
      "id": "BAC",
      "name": {
        "en": "BTEC National Diploma",
        "fr": "Bac"
      }
    },
    ...
  ],
  "experience_levels": [
    {
      "id": "LESS_THAN_6_MONTHS",
      "name": {
        "en": "Less than 6 months",
        "fr": "Moins de 6 mois"
      }
    },
    {
      "id": "6_MONTHS_TO_1_YEAR",
      "name": {
        "en": "6 months - 1 year",
        "fr": "6 mois \u00e0 1 an"
      }
    },
    {
      "id": "1_TO_2_YEARS",
      "name": {
        "en": "1 - 2 years",
        "fr": "1 \u00e0 2 ans"
      }
    },
    ...
  ],
  "salary_currencies": [
    "EUR",
    "USD"
  ],
  "salary_periods": [
    "yearly",
    "monthly",
    "daily",
    "none"
  ],
  "cms_sites_references": [
    "wttj_fr",
    "smgo_fr"
  ]
}

In order to create a job, you will need the following information:

NB: you will also need authorized professions to create any job offer.

HTTP Request

GET https://www.welcomekit.co/api/v1/external/jobs/dependencies

List jobs

curl -X GET "https://www.welcomekit.co/api/v1/external/jobs" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d "organization_reference=Pg4eV6k"

The above command returns JSON structured like this:

[
  {
        "name" : "Fake Job 1",
        "external_reference" : "PROVIDER_REFERENCE1",
        "salary_min" : 45000,
        "organization_reference" : "Pg4eV6k",
        "status" : "draft",
        "salary_period" : "yearly",
        "profile" : "Fake Job Profile",
        "apply_url" : "http://company.com/jobs/superjob/apply/",
        "company_description" : "Fake Company Description.",
        "contract_duration_min" : null,
        "salary_max" : 50000,
        "experience_level" : "1_TO_2_YEARS",
        "salary_currency" : "EUR",
        "department_id" : null,
        "profession_reference" : "sales",
        "cms_sites_references" : "wttj_fr",
        "contract_duration_max" : null,
        "start_date" : "2016-09-01T00:00:00.000+02:00",
        "description" : "Fake Job Description.",
        "contract_type" : "FULL_TIME",
        "is_remote" : true,
        "office_id" : 196,
        "reference" : "WTTJ_gld0A7L",
        "education_level" : "BAC_5"
  },
  {
        "name" : "Fake Job 2",
        "external_reference" : "PROVIDER_REFERENCE2",
        "salary_min" : 45000,
        "organization_reference" : "Pg4eV6k",
        "status" : "draft",
        "salary_period" : "yearly",
        "profile" : "Fake Job Profile",
        "apply_url" : "http://company.com/jobs/superjob/apply/",
        "company_description" : "Fake Company Description.",
        "contract_duration_min" : null,
        "salary_max" : 50000,
        "experience_level" : "1_TO_2_YEARS",
        "salary_currency" : "EUR",
        "department_id" : null,
        "profession_reference" : "sales",
        "cms_sites_references" : "wttj_fr,smgo_fr,btbw_fr",
        "contract_duration_max" : null,
        "start_date" : "2016-09-01T00:00:00.000+02:00",
        "description" : "Fake Job Description.",
        "contract_type" : "FULL_TIME",
        "is_remote" : true,
        "office_id" : 196,
        "reference" : "WTTJ_gld0A7L",
        "education_level" : "BAC_5"
  }
]

This endpoint lets you retrieve all jobs for a given organization.

HTTP Request

GET https://www.welcomekit.co/api/v1/external/jobs

Query Parameters

Parameter Type Required Default Description Example
organization_reference String Reference of the associated organization/company aEioU123
stages Boolean false Return job stages true / false
per_page Integer 100 Number of jobs per page
page Integer 1 Page offset

Retrieve a job

curl -X GET "https://www.welcomekit.co/api/v1/external/jobs/:reference" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d "stages=true"

The above command returns JSON structured like this:

{
  "name" : "Fake Job 2",
  "external_reference" : "PROVIDER_REFERENCE2",
  "salary_min" : 45000,
  "organization_reference" : "Pg4eV6k",
  "status" : "draft",
  "salary_period" : "yearly",
  "profile" : "Fake Job Profile",
  "apply_url" : "http://company.com/jobs/superjob/apply/",
  "company_description" : "Fake Company Description.",
  "contract_duration_min" : null,
  "salary_max" : 50000,
  "experience_level" : "1_TO_2_YEARS",
  "salary_currency" : "EUR",
  "department_id" : null,
  "profession_reference" : "sales",
  "cms_sites_references" : "wttj_fr,smgo_fr",
  "contract_duration_max" : null,
  "start_date" : "2016-09-01T00:00:00.000+02:00",
  "description" : "Fake Job Description.",
  "contract_type" : "FULL_TIME",
  "is_remote" : true,
  "office_id" : 196,
  "reference" : "WTTJ_gld0A7L",
  "education_level" : "BAC_5",
  "stages" : [
    {
      "visible" : true,
      "reference" : "initial",
      "id" : 5395,
      "name" : "Nouveau"
    },
    {
      "reference" : "refused",
      "visible" : true,
      "id" : 5396,
      "name" : "Refusé"
    },
    {
      "id" : 5397,
      "name" : "À rencontrer",
      "reference" : null,
      "visible" : true
    },
    ...
  ]
}

HTTP Request

GET https://www.welcomekit.co/api/v1/external/jobs/:reference

Query Parameters

Parameter Type Required Default Description Example
reference String Job reference aEioU123
stages Boolean false Return job stages true / false

Create a job

curl -X POST "https://www.welcomekit.co/api/v1/external/jobs" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "status": "published",
  "organization_reference": "Pg4eV6k",
  "profession_reference": "sales",
  "name": "Fake Job",
  "company_description": "Fake Company Description.",
  "description": "Fake Job Description.",
  "profile": "Fake Job Profile",
  "contract_type": "FULL_TIME",
  "salary_min": "45000",
  "salary_max": "50000",
  "salary_currency": "EUR",
  "salary_period": "yearly",
  "is_remote": "true",
  "office_zip_code": "75002",
  "education_level": "BAC_5",
  "experience_level": "1_TO_2_YEARS",
  "apply_url": "http://company.com/jobs/superjob/apply/",
  "start_date": "2016-09-01",
  "external_reference": "PROVIDER_REFERENCE",
  "cms_sites_references": "wttj_fr,smgo_fr"
}
EOF

The above command returns JSON structured like this:

{
    "name" : "Fake Job",
    "external_reference" : "PROVIDER_REFERENCE1",
    "salary_min" : 45000,
    "organization_reference" : "Pg4eV6k",
    "status" : "published",
    "salary_period" : "yearly",
    "profile" : "Fake Job Profile",
    "apply_url" : "http://company.com/jobs/superjob/apply/",
    "company_description" : "Fake Company Description.",
    "contract_duration_min" : null,
    "salary_max" : 50000,
    "experience_level" : "1_TO_2_YEARS",
    "salary_currency" : "EUR",
    "department_id" : null,
    "profession_reference" : "sales",
    "cms_sites_references" : "wttj_fr,smgo_fr",
    "contract_duration_max" : null,
    "start_date" : "2016-09-01T00:00:00.000+02:00",
    "description" : "Fake Job Description.",
    "contract_type" : "FULL_TIME",
    "is_remote" : true,
    "office_id" : 196,
    "reference" : "WTTJ_gld0A7L",
    "education_level" : "BAC_5"
}

HTTP Request

POST https://www.welcomekit.co/api/v1/external/jobs

Query Parameters

Parameter Type Required Default Description Example
organization_reference String Reference of the associated organization/company aEioU123
profession_reference String Reference of the associated profession “sales” / “finance” / “dev_backend” / etc. See Professions endpoint
name String Job name Full-Stack Developer
company_description Text Company description (Describe the company)
description Text Job description (Explain the job, not the company)
profile Text Job profile (Explain who you’re looking for)
recruitment_process Text Job Recruitment Process (Delay / Interviews / Tests / etc.)
contract_type String Contract type for this job FULL_TIME / INTERNSHIP / etc. See jobs dependencies
status String Job status draft, published, archived
salary_min Integer Minimum salary for a given salary_period 45000
salary_max Integer Maximum salary for a given salary_period 55000
salary_currency String Currency for the given salary EUR / USD. See jobs dependencies
salary_period String Period for the given salary yearly, monthly, daily, none. See jobs dependencies
is_remote Boolean Is remote work authorized for this job? true / false
contract_duration_min Integer Recommended for ‘TEMPORARY’ contract type Minimum duration of the contract in months. 1, 2, .., 24
contract_duration_max Integer Recommended for 'TEMPORARY’ contract type Maximum duration of the contract in months. 1, 2, .., 24
department_id Integer Department ID. Mainly used by companies which have a careers website managed through WelcomeKit.co 1
office_id Integer See below Office ID. An office is like a “location”. If the office wasn’t created for the targeted company, you will need to contact support@welcomekit.co first. Also, if you don’t have an office_id you can call the API with office_zip_code or office_country_code which may be enough for us to retrieve the associated office. 1
office_address String See below Office zip code (office will be found or created from this). See: comment related to office_id 11b rue Bachaumont
office_zip_code String See below Office zip code (office will be found or created from this). See: comment related to office_id 75002
office_city String See below Office zip code (office will be found or created from this). See: comment related to office_id Paris
office_country_code String See below Office country code (office will be found or created from this). See: comment related to office_id FR
education_level String Minimum education level ID BAC, BAC_5, PHD, etc. See jobs dependencies
experience_level String Minimum experience level ID LESS_THAN_6_MONTHS, 6_MONTHS_TO_1_YEAR, 1_TO_2_YEARS, etc. See jobs dependencies
apply_url String Job application URL. Do not input anything if you want to use WelcomeKit as your ATS http://company.com/jobs/superjob/apply/
start_date String Start date for this job (YYYY-MM-DD) 2015-11-26
external_reference String External provider Reference / ID for this job. (unique constraint)
cms_sites_references String Comma separated list of cms sites references to publish this job wttj_fr,smgo_fr,btbw_fr, wttj_fr, etc. See jobs dependencies

Also, in the required parameters, you have to call this endpoint with AT LEAST ONE of the following attributes:

If the related office is not found from the previous parameters, we will try to create the office if the following conditions are respected:

Update a job

curl -X PUT "https://www.welcomekit.co/api/v1/external/jobs/WTTJ_ZyDmzZ6" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "name": "Fake Job",
  "company_description": "Fake Company Description.",
  "description": "Fake Job Description.",
  "profile": "Fake Job Profile",
  "contract_type": "FULL_TIME",
  "salary_min": "45000",
  "salary_max": "50000",
  "salary_currency": "EUR",
  "salary_period": "yearly",
  "is_remote": "true",
  "office_zip_code": "75002",
  "education_level": "BAC_5",
  "experience_level": "1_TO_2_YEARS",
  "apply_url": "http://company.com/jobs/superjob/apply/",
  "start_date": "2016-09-01",
  "external_reference": "PROVIDER_REFERENCE",
  "cms_sites_references": "wttj_fr,smgo_fr"
}
EOF

The above command returns JSON structured like this:

{
    "name" : "Fake Job",
    "external_reference" : "PROVIDER_REFERENCE1",
    "salary_min" : 45000,
    "organization_reference" : "Pg4eV6k",
    "status" : "draft",
    "salary_period" : "yearly",
    "profile" : "Fake Job Profile",
    "apply_url" : "http://company.com/jobs/superjob/apply/",
    "company_description" : "Fake Company Description.",
    "contract_duration_min" : null,
    "salary_max" : 50000,
    "experience_level" : "1_TO_2_YEARS",
    "salary_currency" : "EUR",
    "department_id" : null,
    "profession_reference" : "sales",
    "cms_sites_references" : "wttj_fr,smgo_fr",
    "contract_duration_max" : null,
    "start_date" : "2016-09-01T00:00:00.000+02:00",
    "description" : "Fake Job Description.",
    "contract_type" : "FULL_TIME",
    "is_remote" : true,
    "office_id" : 196,
    "reference" : "WTTJ_gld0A7L",
    "education_level" : "BAC_5"
}

HTTP Request

PUT https://www.welcomekit.co/api/v1/external/jobs/:reference

Query Parameters

Parameter Type Required Default Description Example
reference String Job reference
profession_reference String Reference for a given profession “sales” / “finance” / “dev_backend” / etc. See Professions endpoint
name String Job name Full-Stack Developer
company_description Text Company description (Describe the company)
description Text Job description (Explain the job, not the company)
profile Text Job profile (Explain who you’re looking for)
recruitment_process Text Job Recruitment Process (Delay / Interviews / Tests / etc.)
contract_type String Contract type for this job FULL_TIME / INTERNSHIP / etc. See jobs dependencies
salary_min Integer Minimum salary for a given salary_period 45000
salary_max Integer Maximum salary for a given salary_period 55000
salary_currency String Currency for the given salary EUR / USD. See jobs dependencies
salary_period String Period for the given salary yearly, monthly, daily, none. See jobs dependencies
is_remote Boolean Is remote work authorized for this job? true / false
contract_duration_min Integer Minimum duration of the contract in months. 1, 2, .., 24
contract_duration_max Integer Maximum duration of the contract in months. 1, 2, .., 24
department_id Integer Department ID. Mainly used by companies which have a careers website managed through WelcomeKit.co 1
office_id Integer Office ID. An office is like a “location”. If the office wasn’t created for the targeted company, you will need to contact support@welcomekit.co first. Also, if you don’t have an office_id you can call the API with office_zip_code or office_country_code which may be enough for us to retrieve the associated office. 1
office_address String Office zip code (office will be found or created from this). See: comment related to office_id 11b rue Bachaumont
office_zip_code String Office zip code (office will be found or created from this). See: comment related to office_id 75002
office_city String Office zip code (office will be found or created from this). See: comment related to office_id Paris
office_country_code String Office country code (office will be found or created from this). See: comment related to office_id FR
education_level String Minimum education level ID BAC, BAC_5, PHD, etc. See jobs dependencies
experience_level String Minimum experience level ID LESS_THAN_6_MONTHS, 6_MONTHS_TO_1_YEAR, 1_TO_2_YEARS, etc. See jobs dependencies
apply_url String Job application URL. Do not input anything if you want to use WelcomeKit as your ATS http://company.com/jobs/superjob/apply/
start_date String Start date for this job (YYYY-MM-DD) 2015-11-26
external_reference String External provider Reference / ID for this job. (unique constraint)
cms_sites_references String Comma separated list of cms sites references to publish this job wttj_fr,smgo_fr,btbw_fr, wttj_fr, etc. See jobs dependencies

Update job status

curl -X PUT "https://www.welcomekit.co/api/v1/external/jobs/:reference/update_status" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "status": "published"
}
EOF

The above command returns JSON structured like this:

{
    "name" : "Fake Job",
    "external_reference" : "PROVIDER_REFERENCE1",
    "salary_min" : 45000,
    "organization_reference" : "Pg4eV6k",
    "status" : "published",
    "salary_period" : "yearly",
    "profile" : "Fake Job Profile",
    "apply_url" : "http://company.com/jobs/superjob/apply/",
    "company_description" : "Fake Company Description.",
    "contract_duration_min" : null,
    "salary_max" : 50000,
    "experience_level" : "1_TO_2_YEARS",
    "salary_currency" : "EUR",
    "department_id" : null,
    "profession_reference" : "sales",
    "cms_sites_references" : "wttj_fr,smgo_fr",
    "contract_duration_max" : null,
    "start_date" : "2016-09-01T00:00:00.000+02:00",
    "description" : "Fake Job Description.",
    "contract_type" : "FULL_TIME",
    "is_remote" : true,
    "office_id" : 196,
    "reference" : "WTTJ_gld0A7L",
    "education_level" : "BAC_5"
}

The default status for a job offer is “draft”. In order to see it live, you will need to publish it.

Summary:

HTTP Request

PUT https://www.welcomekit.co/api/v1/external/jobs/:reference/update_status

Query Parameters

Parameter Type Required Default Description Example
reference String Job reference
status String Job status draft, published, archived

Professions

List available professions

curl -X GET "https://www.welcomekit.co/api/v1/external/professions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"

The above command returns JSON structured like this:

[
    {
        "fullname": "Business > Audit / Finance",
        "reference": "finance"
    },
    {
        "fullname": "Business > Conseil",
        "reference": "consulting"
    },
    {
        "fullname": "Business > Marketing",
        "reference": "marketing"
    },
    {
        "fullname": "Business > Opérations",
        "reference": "operations"
    },
    {
        "fullname": "Business > Logistique / Achats",
        "reference": "logistics"
    },
    {
        "fullname": "Business > Relation client / Support",
        "reference": "support"
    },
    {
        "fullname": "Tech > Développement Backend",
        "reference": "dev_backend"
    },
    {
        "fullname": "Tech > Développement Frontend",
        "reference": "dev_frontend"
    },
    ...
]

In order to create a job, you will need a profession_reference. Professions are used to organized job offers on Welcome to the Jungle, Show must go on, careers websites and other potential job boards.

This endpoint lets you access to the list of all active professions.

HTTP Request

GET https://www.welcomekit.co/api/v1/external/professions

Candidates

List candidates

curl -X GET "https://www.welcomekit.co/api/v1/external/candidates" \
    -d "job_reference=WTTJ_KmqkD1Y" \
    -H "Authorization: Bearer WK_API_KEY"

The above command returns JSON structured like this:

[
  {
    "reference": "wttj-d655345409a6097309156b05",
    "cover_letter": "",
    "created_at": "2016-08-23T12:55:27.206+02:00",
    "job_id": 3027,
    "job_reference": "WTTJ_KmqkD1Y",
    "modal_path": "/dashboard/o/Pg4eV6k/jobs/WTTJ_KmqkD1Y/card/wttj-d655345409a6097309156b05",
    "portfolio_size": 4242,
    "portfolio_url": "http://cdn.com/porfolio.pdf",
    "resume_content_type": "application/pdf",
    "resume_size": 4242,
    "resume_url": "http://cdn.com/resume.pdf",
    "stage_id": 14600,
    "updated_at": "2016-08-23T12:55:27.206+02:00",
    "profile": {
      "address": null,
      "avatar_url": "http://wk.dev/assets/default-avatar-7cbb7b9749a7cf8864001cde13e2a9a94e612bf083430d66ede0966f5bafb296.png",
      "city": null,
      "country_code": null,
      "country_name": null,
      "email": "test@example.com",
      "firstname": "Foo",
      "lastname": "Bar",
      "phone": null,
      "subtitle": null,
      "zip_code": null
    },
    "origin": "external",
    "archived": false
  },
  ...
]

This endpoint lets you retrieve all candidates for a given job reference.

HTTP Request

GET https://www.welcomekit.co/api/v1/external/candidates

Query Parameters

Parameter Type Required Default Description Example
job_reference String Job reference WTTJ_dggjZDa
per_page Integer 100 Number of jobs per page
page Integer 1 Page offset

Retrieve a candidate

curl -X GET "https://www.welcomekit.co/api/v1/external/candidates/:reference" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"

The above command returns JSON structured like this:

{
  "reference": "wttj-d655345409a6097309156b05",
  "cover_letter": "",
  "created_at": "2016-08-23T12:55:27.206+02:00",
  "job_id": 3027,
  "job_reference": "WTTJ_KmqkD1Y",
  "modal_path": "/dashboard/o/Pg4eV6k/jobs/WTTJ_KmqkD1Y/card/wttj-d655345409a6097309156b05",
  "portfolio_size": 4242,
  "portfolio_url": "http://cdn.com/porfolio.pdf",
  "resume_content_type": "application/pdf",
  "resume_size": 4242,
  "resume_url": "http://cdn.com/resume.pdf",
  "stage_id": 14600,
  "updated_at": "2016-08-23T12:55:27.206+02:00",
  "profile": {
    "address": null,
    "avatar_url": "http://wk.dev/assets/default-avatar-7cbb7b9749a7cf8864001cde13e2a9a94e612bf083430d66ede0966f5bafb296.png",
    "city": null,
    "country_code": null,
    "country_name": null,
    "email": "test@example.com",
    "firstname": "Foo",
    "lastname": "Bar",
    "phone": null,
    "subtitle": null,
    "zip_code": null
  },
  "origin": "external",
  "archived": false
}

HTTP Request

GET https://www.welcomekit.co/api/v1/external/candidates/:reference

Query Parameters

Parameter Type Required Default Description Example
reference String Candidate reference wttj-d655345409a6097309156b05

Create a candidate

curl -X POST "https://www.welcomekit.co/api/v1/external/candidates" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "email": "test@example.com",
  "firstname": "Foo",
  "lastname": "Bar",
  "organization_reference": "Pg4eV6k",
  "job_reference": "WTTJ_KmqkD1Y",
  "remote_resume_url": "http://example.com/resume.pdf",
  "remote_portfolio_url": "http://example.com/portfolio.pdf"
}
EOF

The above command returns JSON structured like this:

{
  "reference": "wttj-d655345409a6097309156b05",
  "cover_letter": "",
  "created_at": "2016-08-23T12:55:27.206+02:00",
  "job_id": 3027,
  "job_reference": "WTTJ_KmqkD1Y",
  "modal_path": "/dashboard/o/Pg4eV6k/jobs/WTTJ_KmqkD1Y/card/wttj-d655345409a6097309156b05",
  "portfolio_size": 4242,
  "portfolio_url": "http://cdn.com/porfolio.pdf",
  "resume_content_type": "application/pdf",
  "resume_size": 4242,
  "resume_url": "http://cdn.com/resume.pdf",
  "stage_id": 14600,
  "updated_at": "2016-08-23T12:55:27.206+02:00",
  "profile": {
    "address": null,
    "avatar_url": "http://wk.dev/assets/default-avatar-7cbb7b9749a7cf8864001cde13e2a9a94e612bf083430d66ede0966f5bafb296.png",
    "city": null,
    "country_code": null,
    "country_name": null,
    "email": "test@example.com",
    "firstname": "Foo",
    "lastname": "Bar",
    "phone": null,
    "subtitle": null,
    "zip_code": null
  },
  "origin": "external",
  "archived": false
}

This endpoint lets you create new candidates for a given job_reference.

For example, you could create a Chrome Extension which makes it easy for recruiters to create new candidates… :)

HTTP Request

POST https://www.welcomekit.co/api/v1/external/candidates

Query Parameters

Parameter Type Required Default Description Example
organization_reference String Organization reference Pg4eV6k
job_reference String Job reference WTTJ_KmqkD1Y
job_stage_id Integer Job stage id 42
email String Email test@example.com
firstname String First name John
lastname String Last name Doe
tag_list String Comma separated list of tags foo,bar
subtitle String Subtitle CTO @ WTTJ
phone String Phone number 0606060606
remote_image_url String Avatar url http://example.com/avatar.png
remote_resume_url String Resume url (file type: PDF, DOC, DOCX, ODT maximum file size: 5MB) http://example.com/resume.pdf
remote_portfolio_url String Portfolio url (file type: PDF, maximum file size: 10MB) http://example.com/portfolio.pdf
comment Text A comment about this candidate Lorem ipsum…
archived Boolean Archive user true,false
media_website String Candidate website url https://me.com
media_github String Profile url on Github https://github.com/me
media_stackoverflow String Profile url on Stackoverflow https://stackoverflow.com/users/me
media_dribbble String Profile url on Dribbble https://dribbble.com/me
media_behance String Profile url on Behance https://www.behance.net/me
media_linkedin String Profile url on Linkedin https://fr.linkedin.com/pub/me
media_facebook String Profile url on Facebook https://facebook.com/me
media_instagram String Profile url on Instagram https://www.instagram.com/me
media_medium String Profile url on Medium https://medium.com/@me
media_tumblr String Profile url on Tumblr https://me.tumblr.com
media_vimeo String Profile url on Vimeo https://vimeo.com/me
media_twitter String Profile url on Twitter https://twitter.com/me

Update a candidate

curl -X PUT "https://www.welcomekit.co/api/v1/external/candidates/wttj-d655345409a6097309156b05" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "email": "test@example.com",
  "firstname": "Foo",
  "lastname": "Bar",
  "remote_resume_url": "http://example.com/resume.pdf",
  "remote_portfolio_url": "http://example.com/portfolio.pdf"
}
EOF

The above command returns JSON structured like this:

{
  "reference": "wttj-d655345409a6097309156b05",
  "cover_letter": "",
  "created_at": "2016-08-23T12:55:27.206+02:00",
  "job_id": 3027,
  "job_reference": "WTTJ_KmqkD1Y",
  "modal_path": "/dashboard/o/Pg4eV6k/jobs/WTTJ_KmqkD1Y/card/wttj-d655345409a6097309156b05",
  "portfolio_size": 4242,
  "portfolio_url": "http://cdn.com/porfolio.pdf",
  "resume_content_type": "application/pdf",
  "resume_size": 4242,
  "resume_url": "http://cdn.com/resume.pdf",
  "stage_id": 14600,
  "updated_at": "2016-08-23T12:55:27.206+02:00",
  "profile": {
    "address": null,
    "avatar_url": "http://wk.dev/assets/default-avatar-7cbb7b9749a7cf8864001cde13e2a9a94e612bf083430d66ede0966f5bafb296.png",
    "city": null,
    "country_code": null,
    "country_name": null,
    "email": "test@example.com",
    "firstname": "Foo",
    "lastname": "Bar",
    "phone": null,
    "subtitle": null,
    "zip_code": null
  },
  "origin": "external",
  "archived": false
}

This endpoint lets you update candidates for a given reference.

HTTP Request

PUT https://www.welcomekit.co/api/v1/external/candidates/:reference

Query Parameters

Parameter Type Required Default Description Example
job_stage_id Integer Job stage id 42
email String Email test@example.com
firstname String First name John
lastname String Last name Doe
tag_list String Comma separated list of tags foo,bar
subtitle String Subtitle CTO @ WTTJ
phone String Phone number 0606060606
remote_image_url String Avatar url http://example.com/avatar.png
remote_resume_url String Resume url (file type: PDF, DOC, DOCX, ODT maximum file size: 5MB) http://example.com/resume.pdf
remote_portfolio_url String Portfolio url (file type: PDF, maximum file size: 10MB) http://example.com/portfolio.pdf
archived Boolean Archive user true,false
media_website String Candidate website url https://me.com
media_github String Profile url on Github https://github.com/me
media_stackoverflow String Profile url on Stackoverflow https://stackoverflow.com/users/me
media_dribbble String Profile url on Dribbble https://dribbble.com/me
media_behance String Profile url on Behance https://www.behance.net/me
media_linkedin String Profile url on Linkedin https://fr.linkedin.com/pub/me
media_facebook String Profile url on Facebook https://facebook.com/me
media_instagram String Profile url on Instagram https://www.instagram.com/me
media_medium String Profile url on Medium https://medium.com/@me
media_tumblr String Profile url on Tumblr https://me.tumblr.com
media_vimeo String Profile url on Vimeo https://vimeo.com/me
media_twitter String Profile url on Twitter https://twitter.com/me

Departments

List departments

curl -X GET "https://www.welcomekit.co/api/v1/external/departments" \
    -d "organization_reference=Pg4eV6k" \
    -H "Authorization: Bearer WK_API_KEY"

The above command returns JSON structured like this:

[
  {
    "id": 42,
    "name": "Tech",
    "is_active": true,
    "slug": "tech",
    "description": "Foo bar"
  }
]

This endpoint lets you retrieve all departments (aka teams) for a given organization.

Departments are used on careers websites to organize job offers.

HTTP Request

GET https://www.welcomekit.co/api/v1/external/departments

Query Parameters

Parameter Type Required Default Description Example
organization_reference String Reference of the associated organization/company aEioU123
per_page Integer 100 Number of jobs per page
page Integer 1 Page offset

Retrieve a department

curl -X GET "https://www.welcomekit.co/api/v1/external/departments/:id" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"

The above command returns JSON structured like this:

{
  "id": 42,
  "name": "Tech",
  "is_active": true,
  "slug": "tech",
  "description": "Foo bar"
}

HTTP Request

GET https://www.welcomekit.co/api/v1/external/departments/:id

Query Parameters

Parameter Type Required Default Description Example
id Integer Department id 42

Create a department

curl -X POST "https://www.welcomekit.co/api/v1/external/departments" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "organization_reference": "Pg4eV6k",
  "name": "Tech",
  "is_active": true,
  "description": "Foo bar"
}
EOF

The above command returns JSON structured like this:

{
  "id": 42,
  "name": "Tech",
  "is_active": true,
  "slug": "tech",
  "description": "Foo bar"
}

This endpoint lets you create new departments for a given organization_reference.

HTTP Request

POST https://www.welcomekit.co/api/v1/external/departments

Query Parameters

Parameter Type Required Default Description Example
organization_reference String Organization reference Pg4eV6k
name String Name
slug String Slug (used on careers websites)
is_active Boolean Department active? true / false
description Text Description

NB: the slug is automaticcally generated from the department’s name.

Update a department

curl -X PUT "https://www.welcomekit.co/api/v1/external/departments/:id" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "name": "Whatever",
}
EOF

The above command returns JSON structured like this:

{
  "id": 42,
  "name": "Whatever",
  "is_active": true,
  "slug": "tech",
  "description": "Foo bar"
}

This endpoint lets you update departments for a given id.

HTTP Request

PUT https://www.welcomekit.co/api/v1/external/departments/:id

Query Parameters

Parameter Type Required Default Description Example
id String Department ID
name String Name
slug String Slug
is_active Boolean Department active? true / false
description Text Description

Offices

List offices

curl -X GET "https://www.welcomekit.co/api/v1/external/offices" \
    -d "organization_reference=Pg4eV6k" \
    -H "Authorization: Bearer WK_API_KEY"

The above command returns JSON structured like this:

[
  {
    "id": 42,
    "name": "Paris",
    "address": "11 bis rue Bachaumont",
    "zip_code": "75002",
    "city": "Paris",
    "country_code": "FR",
    "is_active": true,
    "is_headquarter": true,
    "description": "Foo bar"
  }
]

HTTP Request

GET https://www.welcomekit.co/api/v1/external/offices

Query Parameters

Parameter Type Required Default Description Example
organization_reference String Reference of the associated organization/company aEioU123
per_page Integer 100 Number of jobs per page
page Integer 1 Page offset

Retrieve an office

curl -X GET "https://www.welcomekit.co/api/v1/external/offices/:id" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"

The above command returns JSON structured like this:

{
  "id": 42,
  "name": "Paris",
  "address": "11 bis rue Bachaumont",
  "zip_code": "75002",
  "city": "Paris",
  "country_code": "FR",
  "is_active": true,
  "is_headquarter": true,
  "description": "Foo bar"
}

HTTP Request

GET https://www.welcomekit.co/api/v1/external/offices/:id

Query Parameters

Parameter Type Required Default Description Example
id Integer Office id 42

Create an office

curl -X POST "https://www.welcomekit.co/api/v1/external/offices" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "organization_reference": "Pg4eV6k",
  "name": "Paris",
  "address": "11 bis rue Bachaumont",
  "zip_code": "75002",
  "city": "Paris",
  "country_code": "FR",
  "is_active": true,
  "is_headquarter": true,
  "description": "Foo bar"
}
EOF

The above command returns JSON structured like this:

{
  "id": 42,
  "name": "Paris",
  "address": "11 bis rue Bachaumont",
  "zip_code": "75002",
  "city": "Paris",
  "country_code": "FR",
  "is_active": true,
  "is_headquarter": true,
  "description": "Foo bar"
}

This endpoint lets you create new offices for a given organization_reference.

HTTP Request

POST https://www.welcomekit.co/api/v1/external/offices

Query Parameters

Parameter Type Required Default Description Example
organization_reference String Organization reference Pg4eV6k
name String Name
address String Address
zip_code String Zip code
city String City
country_code String Country code US, FR
is_active Boolean Office active? true / false
is_headquarter Boolean Office is organization headquarter? true / false
description Text Description

Update an office

curl -X PUT "https://www.welcomekit.co/api/v1/external/offices/:id" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "name": "France"
}
EOF

The above command returns JSON structured like this:

{
  "id": 42,
  "name": "France",
  "address": "11 bis rue Bachaumont",
  "zip_code": "75002",
  "city": "Paris",
  "country_code": "FR",
  "is_active": true,
  "is_headquarter": true,
  "description": "Foo bar"
}

This endpoint lets you update existing offices for a given id.

HTTP Request

PUT https://www.welcomekit.co/api/v1/external/offices/:id

Query Parameters

Parameter Type Required Default Description Example
id String Office ID
name String Name
address String Address
zip_code String Zip code
city String City
country_code String Country code US, FR
is_active Boolean Office active? true / false
is_headquarter Boolean Office is organization headquarter? true / false
description Text Description

Users

Get current user

curl -X GET "https://www.welcomekit.co/api/v1/external/users/current" \
    -H "Content-Type: application/json" \
    -H "Authorization: bearer WK_API_KEY"

The above command returns JSON structured like this:

{
  "avatar_url": "https://www.welcomekit.co/uploads/user/image/GXj/J/avatar.jpg",
  "display_name": "Foo Bar"
}

This endpoints lets you get:

HTTP Request

GET https://www.welcomekit.co/api/v1/external/users/current

Query Parameters

Parameter Type Required Default Description Example
organizations Boolean Include organizations
jobs Boolean Include jobs
stages Boolean Include jobs stages

Embed

Get informations to build an embed

curl -X GET "https://www.welcomekit.co/api/v1/embed" \
    -d "organization_reference=Pg4eV6k"

The above command returns JSON structured like this:

{
  "name": "Jukebox",
  "jobs": [
    {
      "id": 42,
      "reference": "WTTJ_NQbwwpV",
      "name": "CDI - Full Stack Developper",
      "slug": "full-stack-developper_paris",
      "description": "<p>Hello World…</p>",
      "created_at": {
        "fr": "Le 09 Novembre 2015 à 13h26",
        "en": "09 November 2015 at 13h26"
      },
      "start_date": {
        "fr": "01 Décembre 2015",
        "en": "01 December 2015"
      },
      "office": {
        "id": 42,
        "city": "Paris",
        "country": {
          "fr": "France",
          "en": "France"
        }
      },
      "department": {
        "id": 42,
        "name": "Tech"
      },
      "contract_type": {
        "fr": "CDI",
        "en": "Full-Time"
      },
      "cms_sites_references": [
        "wttj_fr"
      ]
    }
  ],
  "sites": [
    {
      "reference": "wk-careers_wttj",
      "kind": "single",
      "url": "http://welcometothejungle.co"
    }
  ]
}

HTTP Request

GET https://www.welcomekit.co/api/v1/embed

Query Parameters

Parameter Type Required Default Description Example
organization_reference String Organization reference Pg4eV6k

Errors

The Welcome Kit API uses the following HTTP status codes:

Status Code Meaning
400 Bad Request – Your request is invalid
401 Unauthorized – Your OAuth access_token is wrong
403 Forbidden – Your not allowed to access this resource
404 Not Found – Ressource could not be found
405 Method Not Allowed – You tried to use an endpoint with an invalid method
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Error messages are returned in JSON format as described below:

{
  "error": "unauthorized",
  "error_description": "You are not member of this organization"
}
Error Codes Meaning
not_found Resource not found
validation_failed Some parameters are invalid
unauthorized You OAuth access_token is invalid
invalid_scope OAuth access_token scope is not authorized

FAQ

Get published jobs count?

curl -X HEAD -i "https://www.welcomekit.co/api/v1/external/jobs" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d "organization_reference=Pg4eV6k" \
    -d "status=published"

The above command returns the following headers:

[...]
X-Total: 18
X-Total-Pages: 1
X-Per-Page: 100
X-Page: 1
X-Offset: 0
[...]

You just need to read the X-Total header of the GET /external/jobs endpoint.

NB: