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:

Get all your candidates for a given job
Create candidates for a given job
Create and update jobs for a given organization
Configure your organization (departments / offices / etc.)

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

curl "WK_API_ENDPOINT_HERE"
  -H "Authorization: Bearer WK_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:

1/ Either in a header that looks like the following:

Authorization: Bearer WK_API_KEY

2/ Or, through query string:

?access_token=WK_API_KEY

You must replace WK_API_KEY with your personal 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 all candidates (limited to user’s role)
`candidates_r`	Read access on all candidates (limited to user’s role)
`my_candidates_rw`	Read and Write access on all candidates this user created through the API (mainly useful for synchronization with external services without giving access to all your candidates)
`documents_rw`	Read and Write access on your candidates files
`documents_r`	Read access on your candidates files
`emails_rw`	Read and Write access on your candidates emails
`emails_r`	Read access on your candidates emails
`comments_w`	Write access on your candidates comments
`images_r`	Read access to your images
`moves_r`	Read access on candidates moves
`videos_r`	Read access on your video files

Jobs

Get jobs dependencies

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

{
  "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"
      }
    },
    ...
  ],
  "remote_levels": [
    {
      "id": "fulltime",
      "name": {
        "en": "Possible full remote",
        "fr": "Télétravail total possible"
      }
    },
    {
      "id": "partial",
      "name": {
        "en": "Partial remote authorized",
        "fr": "Télétravail partiel autorisé"
      }
    },
    {
      "id": "punctual",
      "name": {
        "en": "Occasional remote authorized",
        "fr": "Télétravail ponctuel autorisé"
      }
    },
    {
      "id": "no",
      "name": {
        "en": "Non authorized",
        "fr": "Non autorisé"
      }
    }
  ],
  "salary_currencies": [
    "EUR",
    "USD"
  ],
  "salary_periods": [
    "yearly",
    "monthly",
    "daily",
    "none"
  ],
  "cms_sites_references": [
    "wttj_fr",
    "smgo_fr"
  ]
}

This endpoint requires jobs_r or jobs_rw scope.

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

salary_currencies
- authorized currencies when specifying a salary
- examples: EUR, USD
salary_periods
- authorized periods when specifying a salary
- examples: yearly, monthly, etc.
contract_types
- authorized contract types
- examples: FULL_TIME, PART_TIME, TEMPORARY, FREELANCE, INTERNSHIP, APPRENTICESHIP
experience_levels
- authorized experience levels
- examples: 1_TO_2_YEARS, MORE_THAN_15_YEARS, etc.
education_levels
- authorized education levels
- examples: PHD, NO_DIPLOMA, etc.
remote_levels
- authorized remote levels
- examples: fulltime, partial, punctual, no
cms_sites_references
- authorized cms sites references
- examples: wttj_fr,smgo_fr,btbw_fr etc.

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

HTTP Request

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

List all jobs

curl -X GET -G "https://www.welcomekit.co/api/v1/external/jobs/all" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d "status=published" \
    -d "created_after=2017-10-30"

[
  {
    "name" : "Fake Job 1",
    "external_reference" : "PROVIDER_REFERENCE1",
    "organization_reference" : "Pg4eV6k",
    "status" : "draft",
    "profile" : "Fake Job Profile",
    "apply_url" : "http://company.com/jobs/superjob/apply/",
    "company_description" : "Fake Company Description.",
    "contract_duration_min" : null,
    "experience_level" : "1_TO_2_YEARS",
    "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",
    "language": "en",
    "salary": {
      "min": "30000",
      "max": "40000",
      "currency": "EUR",
      "period": "yearly"
    },
    "remote" : "no",
    "office_id" : 196,
    "reference" : "WTTJ_gld0A7L",
    "education_level" : "BAC_5",
    "created_at" : "2017-11-13T17:15:26.146+01:00",
    "updated_at" : "2017-11-13T17:15:26.146+01:00",
    "published_at" : "2017-11-13T18:00:01.146+01:00",
    "archived_at" : null
  },
  {
    "name" : "Fake Job 2",
    "external_reference" : "PROVIDER_REFERENCE2",
    "organization_reference" : "Pg4eV6k",
    "status" : "draft",
    "profile" : "Fake Job Profile",
    "apply_url" : "http://company.com/jobs/superjob/apply/",
    "company_description" : "Fake Company Description.",
    "contract_duration_min" : null,
    "experience_level" : "1_TO_2_YEARS",
    "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",
    "salary": {
      "min": "30000",
      "max": "40000",
      "currency": "EUR",
      "period": "yearly"
    },
    "remote" : "fulltime",
    "office_id" : 196,
    "reference" : "WTTJ_gld0A7L",
    "education_level" : "BAC_5",
    "created_at" : "2017-11-13T17:15:26.146+01:00",
    "updated_at" : "2017-11-13T17:15:26.146+01:00",
    "published_at" : "2017-11-13T18:00:01.146+01:00",
    "archived_at" : null
  }
]

This endpoint requires su_jobs_r scope.

This endpoint lets you retrieve all jobs for all organizations.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description	Example
`stages`	Boolean	false	Returns job stages	true / false
`websites`	Boolean	false	Returns associated websites URLs	true / false
`office`	Boolean	false	Returns associated office description	true / false
`status`	String		Returns jobs with this specific status	draft / published / archived
`contract_type`	String		Returns jobs with this specific contract type	FULL_TIME / …
`per_page`	Integer	100	Number of jobs per page
`page`	Integer	1	Page offset
`created_after`	String		Returns jobs created after this date (YYYY-MM-DD)	2015-11-26
`updated_after`	String		Returns jobs updated after this date (YYYY-MM-DD)	2015-11-26
`published_after`	String		Returns jobs published after this date (YYYY-MM-DD)	2015-11-26

List jobs

curl -X GET -G "https://www.welcomekit.co/api/v1/external/jobs" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d "organization_reference=Pg4eV6k" \
    -d "status=published" \
    -d "created_after=2017-10-30"

[
  {
    "name" : "Fake Job 1",
    "external_reference" : "PROVIDER_REFERENCE1",
    "organization_reference" : "Pg4eV6k",
    "status" : "draft",
    "profile" : "Fake Job Profile",
    "apply_url" : "http://company.com/jobs/superjob/apply/",
    "company_description" : "Fake Company Description.",
    "contract_duration_min" : null,
    "experience_level" : "1_TO_2_YEARS",
    "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",
    "language": "en",
    "salary": {
      "min": "30000",
      "max": "40000",
      "currency": "EUR",
      "period": "yearly"
    },
    "remote" : "no",
    "office_id" : 196,
    "reference" : "WTTJ_gld0A7L",
    "education_level" : "BAC_5",
    "created_at" : "2017-11-13T17:15:26.146+01:00",
    "updated_at" : "2017-11-13T17:15:26.146+01:00",
    "published_at" : "2017-11-13T18:00:01.146+01:00",
    "archived_at" : null
  },
  {
    "name" : "Fake Job 2",
    "external_reference" : "PROVIDER_REFERENCE2",
    "organization_reference" : "Pg4eV6k",
    "status" : "draft",
    "profile" : "Fake Job Profile",
    "apply_url" : "http://company.com/jobs/superjob/apply/",
    "company_description" : "Fake Company Description.",
    "contract_duration_min" : null,
    "experience_level" : "1_TO_2_YEARS",
    "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",
    "salary": {
      "min": "30000",
      "max": "40000",
      "currency": "EUR",
      "period": "yearly"
    },
    "remote" : "fulltime",
    "office_id" : 196,
    "reference" : "WTTJ_gld0A7L",
    "education_level" : "BAC_5",
    "created_at" : "2017-11-13T17:15:26.146+01:00",
    "updated_at" : "2017-11-13T17:15:26.146+01:00",
    "published_at" : "2017-11-13T18:00:01.146+01:00",
    "archived_at" : null
  }
]

This endpoint requires jobs_r or jobs_rw scope.

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	Returns job stages	true / false
`websites`	Boolean		false	Returns associated websites URLs	true / false
`office`	Boolean		false	Returns associated office description	true / false
`status`	String			Returns jobs with this specific status	draft / published / archived
`per_page`	Integer		100	Number of jobs per page
`page`	Integer		1	Page offset
`created_after`	String			Returns jobs created after this date (YYYY-MM-DD)	2015-11-26
`updated_after`	String			Returns jobs updated after this date (YYYY-MM-DD)	2015-11-26
`published_after`	String			Returns jobs published after this date (YYYY-MM-DD)	2015-11-26

Retrieve a job

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

{
  "name" : "Fake Job 2",
  "external_reference" : "PROVIDER_REFERENCE2",
  "organization_reference" : "Pg4eV6k",
  "status" : "draft",
  "profile" : "Fake Job Profile",
  "apply_url" : "http://company.com/jobs/superjob/apply/",
  "company_description" : "Fake Company Description.",
  "contract_duration_min" : null,
  "experience_level" : "1_TO_2_YEARS",
  "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",
  "language": "en",
  "salary": {
    "min": "30000",
    "max": "40000",
    "currency": "EUR",
    "period": "yearly"
  },
  "remote" : "fulltime",
  "office_id" : 196,
  "reference" : "WTTJ_gld0A7L",
  "education_level" : "BAC_5",
  "stages" : [
    {
      "visible" : true,
      "reference" : "initial",
      "id" : 5395,
      "name" : "Nouveau",
      "candidates_count": 4
    },
    {
      "reference" : "refused",
      "visible" : true,
      "id" : 5396,
      "name" : "Refusé",
      "candidates_count": 2
    },
    {
      "id" : 5397,
      "name" : "À rencontrer",
      "reference" : null,
      "visible" : true,
      "candidates_count": 1
    },
    ...
  ],
  "candidates_count": 13,
  "created_at" : "2017-11-13T17:15:26.146+01:00",
  "updated_at" : "2017-11-13T17:15:26.146+01:00",
  "published_at" : null,
  "archived_at" : null,
  "websites" : [
     {
        "reference" : "wttj_fr",
        "name" : "Welcome to the Jungle",
        "url" : "http://preprod.welcometothejungle.co/companies/wttj/jobs/fake-job-2"
     },
    ...
  ],
  "application_fields": [
    {"name": "resume", "mode": "mandatory"},
    {"name": "portfolio", "mode": "disabled"},
    ...
  ],
  "organization": {
    "name": "wttj",
    "slug": "wttj",
    "description": "Lorem ipsum",
    "logo": "https://....."
  }
}

This endpoint requires jobs_r or jobs_rw scope. Availability of candidates counters (total and per stage ones) requires candidates_r or candidates_rw scope and setting the query parameter candidates_count to 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	Returns job stages	true / false
`websites`	Boolean		false	Returns associated websites URLs	true / false
`office`	Boolean		false	Returns associated office description	true / false
`candidates_count`	Boolean		false	Returns candidates counters (total and per stage ones)	true / false
`application_fields`	Boolean		false	Returns application fields	true / false
`organization`	Boolean		false	Returns organization fields	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",
  "language": "en",
  "salary_min": "30000",
  "salary_max": "40000",
  "salary_currency": "EUR",
  "salary_period": "yearly",
  "remote": "fulltime",
  "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

{
  "name" : "Fake Job",
  "external_reference" : "PROVIDER_REFERENCE1",
  "organization_reference" : "Pg4eV6k",
  "status" : "published",
  "profile" : "Fake Job Profile",
  "apply_url" : "http://company.com/jobs/superjob/apply/",
  "company_description" : "Fake Company Description.",
  "contract_duration_min" : null,
  "experience_level" : "1_TO_2_YEARS",
  "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",
  "language": "en",
  "salary": {
    "min": "30000",
    "max": "40000",
    "currency": "EUR",
    "period": "yearly"
  },
  "remote" : "fulltime",
  "office_id" : 196,
  "reference" : "WTTJ_gld0A7L",
  "education_level" : "BAC_5",
  "created_at" : "2017-11-13T17:15:26.146+01:00",
  "updated_at" : "2017-11-13T17:15:26.146+01:00",
  "published_at" : "2017-11-13T18:00:01.146+01:00",
  "archived_at" : null
}

This endpoint requires jobs_rw scope.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Description	Example
`organization_reference`	String	✔	Reference of the associated organization/company	aEioU123
`profession_reference`	String	✔	Reference of the associated profession	“sales” / “market_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
`language`	String	✔	Language for this job	‘fr’ See languages for available languages
`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		[DEPRECATED] Is remote work authorized for this job?	true / false
`remote`	String		Is remote work authorized for this job?	fulltime / partial / punctual / no
`contract_duration_min`	Integer	Recommended for 'TEMPORARY’ contract type	Minimum duration of the contract in months.	1, 2, .., 36
`contract_duration_max`	Integer	Recommended for 'TEMPORARY’ contract type	Maximum duration of the contract in months.	1, 2, .., 36
`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”. You can use the `List Offices` API to retrieve the list of office ids. 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 (if any) or dynamically create a new one.	1
`office_address`	String	See below	Office address (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 city (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:

office_id
office_address
office_zip_code
office_city (mandatory for creation)
office_country_code (mandatory for creation)

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

access to offices_rw scope
all mandatory attributes to create an office: office_city, office_country_code

Update a job

This endpoint requires jobs_rw scope.

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",
  "language": "en",
  "salary_min": "30000",
  "salary_max": "40000",
  "salary_currency": "EUR",
  "salary_period": "yearly",
  "remote": "punctual",
  "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

{
  "name" : "Fake Job",
  "external_reference" : "PROVIDER_REFERENCE1",
  "organization_reference" : "Pg4eV6k",
  "status" : "draft",
  "profile" : "Fake Job Profile",
  "apply_url" : "http://company.com/jobs/superjob/apply/",
  "company_description" : "Fake Company Description.",
  "contract_duration_min" : null,
  "experience_level" : "1_TO_2_YEARS",
  "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",
  "language": "en",
  "salary": {
    "min": "30000",
    "max": "40000",
    "currency": "EUR",
    "period": "yearly"
  },
  "remote" : "punctual",
  "office_id" : 196,
  "reference" : "WTTJ_gld0A7L",
  "education_level" : "BAC_5",
  "created_at" : "2017-11-13T17:15:26.146+01:00",
  "updated_at" : "2017-11-13T17:15:26.146+01:00",
  "published_at" : null,
  "archived_at" : null
}

HTTP Request

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

Query Parameters

Parameter	Type	Required	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
`language`	String		Language for this job	'en’ See languages for complete list
`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		[DEPRECATED] Is remote work authorized for this job?	true / false
`remote`	String		Is remote work authorized for this job?	fulltime / partial / punctual / no
`contract_duration_min`	Integer		Minimum duration of the contract in months.	1, 2, .., 36
`contract_duration_max`	Integer		Maximum duration of the contract in months.	1, 2, .., 36
`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

{
  "name" : "Fake Job",
  "external_reference" : "PROVIDER_REFERENCE1",
  "organization_reference" : "Pg4eV6k",
  "status" : "published",
  "profile" : "Fake Job Profile",
  "apply_url" : "http://company.com/jobs/superjob/apply/",
  "company_description" : "Fake Company Description.",
  "contract_duration_min" : null,
  "experience_level" : "1_TO_2_YEARS",
  "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",
  "language": "en",
  "salary": {
    "min": "30000",
    "max": "40000",
    "currency": "EUR",
    "period": "yearly"
  },
  "remote" : "punctual",
  "office_id" : 196,
  "reference" : "WTTJ_gld0A7L",
  "education_level" : "BAC_5",
  "created_at" : "2017-11-13T17:15:26.146+01:00",
  "updated_at" : "2017-11-13T17:15:26.146+01:00",
  "published_at" : "2017-11-13T17:15:26.146+01:00",
  "archived_at" : null
}

This endpoint requires jobs_rw scope.

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

Summary:

draft: private job offer (still visible on main view of the dashboard)
published: public job offer visible on all cms_sites_references
archived: private job offer (visible from archived jobs only)

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 -G "https://www.welcomekit.co/api/v1/external/professions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"

[
    {
        "fullname_translations": {
            "fr": "Business  > Business Development",
            "es": "Negocios  > Desarrollo de negocio",
            "en": "Business  > Business Development",
        },
        "fullname": "Business  > Business Development",
        "reference": "business_development"
    },
    {
        "fullname_translations": {
            "fr": "Business  > Acheteur",
            "es": "Negocios  > Compras",
            "en": "Business  > Purchasing",
        },
        "fullname": "Business  > Purchasing",
        "reference": "purchasing"
    },
    {
        "fullname_translations": {
            "fr": "Business  > Commercial",
            "es": "Negocios  > Comercial",
            "en": "Business  > Sales",
        },
        "fullname": "Business  > Sales",
        "reference": "sales"
    },
    ...
]

In order to create a job, you will need a profession_reference. Professions are used to organized job offers on Welcome to the Jungle, 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

Departments

List departments

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

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

This endpoint requires departments_r or departments_rw scope.

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 -G "https://www.welcomekit.co/api/v1/external/departments/:id" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"

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

This endpoint requires departments_r or departments_rw scope.

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

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

This endpoint requires departments_rw scope.

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	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 automatically 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

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

This endpoint requires departments_rw scope.

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	Description	Example
`id`	String	✔	Department ID
`name`	String		Name
`slug`	String		Slug
`is_active`	Boolean		Department active?	true / false
`description`	Text		Description

Candidates

List candidates

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

[
  {
    "reference": "wttj-d655345409a6097309156b05",
    "cover_letter": "",
    "created_at": "2016-08-23T12:55:27.206+02:00",
    "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,
    "stage":{
      "id": 14600,
      "name":"Refusé",
      "reference":"refused",
      "visible":true
    },
    "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 requires candidates_* or my_candidates_* scope.

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
`email`	String				example@example.co
`origin`	String			Filter by origin	website:cms:wttj_fr
`referrer`	String			Filter by referrer	www.linkedin.com
`job_stage_id`	String			Filter by job stage id	123
`job_stage_reference`	String			Filter by job stage reference	refused
`archived`	String		both	Only returns archived candidates or not	true/false
`created_after`	String			Only returns candidates created after this date (YYYY-MM-DD)	2015-11-26
`updated_after`	String			Only returns candidates updated after this date (YYYY-MM-DD)	2015-11-26
`per_page`	Integer		100	Number of jobs per page
`page`	Integer		1	Page offset
`stage`	Boolean		false	Returns related job stage (ie. refused, hired, etc.)	true/false
`tags`	Boolean		false	Returns related tags	true/false

Retrieve a candidate

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

{
  "reference": "wttj-d655345409a6097309156b05",
  "cover_letter": "",
  "created_at": "2016-08-23T12:55:27.206+02:00",
  "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,
  "stage":{
    "id": 14600,
    "name":"Refusé",
    "reference":"refused",
    "visible":true
  },
  "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
  },
  "tags": ["ruby","react","go","elixir","react native"],
  "origin": "external",
  "archived": false
}

This endpoint requires candidates_* or my_candidates_* scope.

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
`stage`	Boolean		false	Returns related job stage (ie. refused, hired, etc.)	true/false
`tags`	Boolean		false	Returns related tags	true/false

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

{
  "reference": "wttj-d655345409a6097309156b05",
  "cover_letter": "",
  "created_at": "2016-08-23T12:55:27.206+02:00",
  "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 requires candidates_rw or my_candidates_rw scope.

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… :)

Also, if you don’t want to give full access to all your candidates to external services, you may use the my_candidates_rw scope which will let them create candidates and only access to the candidates they created.

HTTP Request

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

Query Parameters

Parameter	Type	Required	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
`cover_letter`	String		Cover letter	Lorem ipsum…
`referrer`	String		Referrer	http://github.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

{
  "reference": "wttj-d655345409a6097309156b05",
  "cover_letter": "",
  "created_at": "2016-08-23T12:55:27.206+02:00",
  "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 requires candidates_rw or my_candidates_rw scope.

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	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
`cover_letter`	String	Cover letter	Lorem ipsum…

Comments

Create a comment

curl -X POST "https://www.welcomekit.co/api/v1/external/comments" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "candidate_reference": "wttj-d655345409a6097309156b05",
  "content": "Foo"
}
EOF

{
  "id":83316,
  "content":"<p>Foo</p>\n",
  "raw_content":"Foo"
}

This endpoint requires comments_w, and candidates_* or my_candidates_* scopes.

This endpoint lets you create new comments for a given candidate_reference.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Default	Description	Example
`candidate_reference`	String	✔		Candidate reference	wttj-d655345409a6097309156b05
`content`	String	✔		Comment content (plain text, html or markdown)	Lipsum.

Emails

List candidate emails

curl -X GET -G "https://www.welcomekit.co/api/v1/external/emails" \
    -d "candidate_reference=wttj-d655345409a6097309156b05" \
    -H "Authorization: Bearer WK_API_KEY"

[
  {
    "id": 12345,
    "subject": "Greetings",
    "body": "Email body",
    "from_email": "test@example.com",
    "to": "example@test.com",
    "created_at": "2018-01-03T16:17:07.501+01:00",
    "origin": "api",
    "candidate_reference": "wttj-d655345409a6097309156b05",
    "attachments": []
  },
  ...
]

This endpoint requires emails_*, and candidates_* or my_candidates_* scopes.

This endpoint lets you retrieve all emails for a given candidate reference.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Default	Description	Example
`candidate_reference`	String	✔		Candidate reference	wttj-d655345409a6097309156b05
`per_page`	Integer		100	Number of emails per page
`page`	Integer		1	Page offset

Create an email

curl -X POST "https://www.welcomekit.co/api/v1/external/emails" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "candidate_reference": "wttj-d655345409a6097309156b05",
  "subject": "Greetings",
  "body": "Email body",
  "from_email": "test@example.com",
  "to": "example@test.com",
  "remote_file_urls": [
    {
      "filename": "resume",
      "url": "http://example.com/resume.pdf"
    }
  ]
}
EOF

{
  "id": 12345,
  "subject": "Greetings",
  "body": "Email body",
  "from_email": "test@example.com",
  "to": "example@test.com",
  "created_at": "2018-01-03T16:17:07.501+01:00",
  "origin": "api",
  "candidate_reference": "wttj-d655345409a6097309156b05",
  "attachments": [
    {
      "filename": "resume",
      "file_url": "http://example.com/resume.pdf",
      "size": 433348,
      "content_type": "application/pdf"
    }
  ]
}

This endpoint requires emails_rw, and my_candidtates_rw or candidates_rw scope.

This endpoint lets you create a new email for a given candidate_reference.

For example, it may be useful if you send emails through an external service and you want to consolidate all the emails related to your candidates in WelcomeKit.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Default	Description	Example
`candidate_reference`	String	✔		Candidate reference	wttj-d655345409a6097309156b05
`subject`	String	✔		Email subject	Hello World
`body`	String	✔		Email body (plain text, markdown, html)	Lipsum.
`from_email`	String	✔		Email sender	whatever@wherever.com
`to`	String	✔		Email receiver	whatever@wherever.com
`send_email`	String		false	Let Welcome Kit send the related email to the candidate?	true/false
`remote_file_urls`	Array			Email attachments (PDF, JPG, etc.)	`[ {"filename": "resume", "url": "http://example.com/resume.pdf"} ]`

Documents

List candidate documents

curl -X GET -G "https://www.welcomekit.co/api/v1/external/documents" \
    -d "candidate_reference=wttj-d655345409a6097309156b05" \
    -H "Authorization: Bearer WK_API_KEY"

[
  {
    "id": 20,
    "job_reference": "WTTJ_KmqkD1Y",
    "candidate_reference": "wttj-d655345409a6097309156b05",
    "filename": "example",
    "file_url": "http://example.com/example.pdf",
    "size": 433994,
    "content_type": "application/pdf",
    "created_at": "2018-01-08T11:46:02.990+01:00"
  },
  ...
]

This endpoint requires documents_*, and candidates_* or my_candidates_* scopes.

This endpoint lets you retrieve all attached documents for a given candidate_reference.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Default	Description	Example
`candidate_reference`	String	✔		Candidate reference	wttj-d655345409a6097309156b05
`per_page`	Integer		100	Number of documents per page
`page`	Integer		1	Page offset

Attach documents to a candidate

curl -X POST "https://www.welcomekit.co/api/v1/external/documents" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "candidate_reference": "wttj-d655345409a6097309156b05",
  "remote_file_urls": [
    {"filename": "resume", "url": "http://example.com/resume.pdf"},
    {"filename": "portfolio", "url": "http://example.com/portfolio.pdf"}
  ]
}
EOF

[
  {
    "id": 20,
    "job_reference": "WTTJ_KmqkD1Y",
    "candidate_reference": "wttj-d655345409a6097309156b05",
    "filename": "example",
    "file_url": "http://example.com/resume.pdf",
    "size": 433994,
    "content_type": "application/pdf",
    "created_at": "2018-01-08T11:46:02.990+01:00"
  },
  ...
]

This endpoint requires documents_rw, and my_candidtates_rw or candidates_rw scope.

This endpoint lets you attach new documents for a given candidate_reference.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Default	Description	Example
`candidate_reference`	String	✔		Candidate reference	wttj-d655345409a6097309156b05
`remote_file_urls`	Array			Array of files	`[ {"filename": "resume", "url": "http://example.com/resume.pdf"} ]`

Offices

List offices

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

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

This endpoint requires offices_r or offices_rw scope.

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 -G "https://www.welcomekit.co/api/v1/external/offices/:id" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"

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

This endpoint requires offices_r or offices_rw scope.

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_headquarter": true
}
EOF

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

This endpoint requires offices_rw scope.

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	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_headquarter`	Boolean		Office is organization headquarter?	true / false

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

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

This endpoint requires offices_rw scope.

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	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_headquarter`	Boolean		Office is organization headquarter?	true / false

Users

Get current user

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

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

This endpoint requires me_r scope.

This endpoints lets you get:

Information about the current user
All organizations this user has access to
All jobs related to these organizations
All stages (aka columns) related to these jobs

HTTP Request

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

Query Parameters

Parameter	Type	Description
`organizations`	Boolean	Include organizations
`jobs`	Boolean	Include jobs
`stages`	Boolean	Include jobs stages

Sectors

List available sectors

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

[
    {
        "id": "2",
        "fullname": {
            "es": "Tecnología > Big data",
            "en": "Tech > Big data",
            "fr": "Tech > Big data"
        },
        "parent": {
            "es": "Tecnología",
            "en": "Tech",
            "fr": "Tech",
            "_id": "1"
        },
        "names": {
            "es": "Big data",
            "en": "Big data",
            "fr": "Big data"
        },
        "reference": "big_data"
    },
    {
        "id": "3",
        "fullname": {
            "es": "Tecnología > Software",
            "en": "Tech > Software",
            "fr": "Tech > Logiciels"
        },
        "parent": {
            "es": "Tecnología",
            "en": "Tech",
            "fr": "Tech",
            "_id": "1"
        },
        "names": {
            "es": "Software",
            "en": "Software",
            "fr": "Logiciels"
        },
        "reference": "software"
    }
    ...
]

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

HTTP Request

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

Tools

List tools

curl -X GET -G "https://www.welcomekit.co/api/v1/external/tools" \
    -H "Authorization: Bearer WK_API_KEY"

curl -X GET -G "https://www.welcomekit.co/api/v1/external/tools" \
    -d "name=react"
    -H "Authorization: Bearer WK_API_KEY"

[
    {
        "thumb_url": "https://welcomekit.co/img/aws.png",
        "tool_category": {
            "name": "Product Management",
            "reference": "pm",
            "id": 1
        },
        "alternative_names": "Aws Cloudfront, Cloudfront",
        "name": "Amazon Cloudfront",
        "id": 35
    },
    {
        "thumb_url": "https://welcomekit.co/img/js.png",
        "tool_category": {
            "name": "Front",
            "reference": "frontend",
            "id": 2
        },
        "alternative_names": "JS",
        "name": "Javascript",
        "id": 351
    }
  ...
]

This endpoint requires tools_r scope.

This endpoint lets you retrieve all tools.

HTTP Request

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

Query Parameters

Parameter	Type	Default	Description
`per_page`	Integer	100	Number of jobs per page
`page`	Integer	1	Page offset
`name`	String	false	Filter on name (search on name & alternative names)

Embed

Get information to build an embed

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

{
  "name": "Welcome to the Jungle",
  "jobs": [
    {
      "id": 42,
      "reference": "WTTJ_NQbwwpV",
      "name": "CDI - Full Stack Developper",
      "slug": "full-stack-developper_paris",
      "description": "<p>Hello World…</p>",
      "profile": "<p>Hello World…</p>",
      "recruitment_process": "<p>Hello World…</p>",
      "salary": {
        "min": "30000",
        "max": "40000",
        "currency": "EUR",
        "period": "yearly"
      },
      "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,
        "name": "Paris",
        "address": "11 bis rue Bachaumont",
        "zip_code": "75002",
        "district": "Paris",
        "city": "Paris",
        "country": {
          "fr": "France",
          "en": "France"
        }
      },
      "department": {
        "id": 42,
        "name": "Tech"
      },
      "contract_type": {
        "fr": "CDI",
        "en": "Full-Time"
      },
      "cms_sites_references": [
        "wttj_fr"
      ],
      "websites_urls" : [
         {
            "reference" : "wttj_fr",
            "url" : "https://www.welcometothejungle.co/companies/wttj/jobs/fake-job-2"
         },
        ...
      ]
    }
  ],
  "websites": [
    {
      "reference": "wttj_careers",
      "kind": "single",
      "url": "https://wttj.welcomekit.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

Languages

Get languages

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

[
    {
        "name": "English",
        "reference": "en"
    },
    {
        "name": "French",
        "reference": "fr"
    },
    {
        "name": "Spanish; Castilian",
        "reference": "es"
    }
]

In order to create a job, you will need a langague. This endpoint lets you access to the list of all active languages.

HTTP Request

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

Images

List available images

curl -X GET -G "https://www.welcomekit.co/api/v1/external/images" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d "organization_reference=Pg4eV6k" \

[
  {
   "name": "WTTJ team",
   "description": "Welcome To The Jungle team",
   "file": {
             "url": "https://cdn.welcometothejungle.co/uploads/website_organization/cover_image/wttj_fr/fr-wttj.jpg",
             "large": {"url": "https://cdn.welcometothejungle.co/uploads/website_organization/cover_image/wttj_fr/large_fr-wttj.jpg"},
             "medium": {"url": "https://cdn.welcometothejungle.co/uploads/website_organization/cover_image/wttj_fr/medium_fr-wttj.jpg"},
             "small": {"url": "https://cdn.welcometothejungle.co/uploads/website_organization/cover_image/wttj_fr/small_fr-wttj.jpg"},
             "thumb": {"url": "https://cdn.welcometothejungle.co/uploads/website_organization/cover_image/wttj_fr/thumb_fr-wttj.jpg"}
           },
    "created_at": "2019-03-28T10:00:01.403+01:00",
    "updated_at": "2019-03-28T10:00:01.403+01:00"
  },
  ...
]

This endpoint requires the images_r or su_images_r scope.

This endpoint lets you access to the list of your images (scope images_r) or to all images (scope su_images_r).

The dimensions of each image type are as follows:

“standard” image dimensions fit within 2000x3000 px
“large” image dimensions fit within 1200x2000 px
“medium” image dimensions fit within 850x850 px
“small” image dimensions fit within 650x650 px
“thumb” image dimensions fit within 200x200 px

HTTP Request

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

Query Parameters

Parameter	Type	Required	Default	Description	Example
`organization_reference`	String	✔		Organization reference	Pg4eV6k
`per_page`	Integer		100	Number of images per page
`page`	Integer		1	Page offset

Moves

List moves

curl -X GET -G "https://www.welcomekit.co/api/v1/external/moves" \
    -d "organization_reference=wttj" \
    -d "job_reference=V-1841-0" \
    -H "Authorization: Bearer WK_API_KEY"

[
  {
    "candidate": {"reference": "dc-41e24bb6e4a27"},
    "from": {
              "stage": {"id": 547, "name": "To meet", "reference": "to-meet"},
              "organization": {"reference": "wttj"},
              "job": {"reference": "V-1841-0"}
            },
    "to": {
            "stage": {"id": 295, "name": "Interviewed", "reference": "interviewed"},
            "organization": {"reference": "wttj"},
            "job": {"reference": "V-1841-0"}
          },
    "created_at": "2019-03-27T14:15:38.430+01:00",
    "updated_at": "2019-03-27T14:15:38.430+01:00"
  },
  ...
]

This endpoint requires moves_r scope.

There are 3 types of moves:

a candidate moves from one job stage to another one (no job/organization change)
a candidate moves from one job to another one (no organization change)
a candidate moves from one job to another one from an another organization

Please note that a job stage is not included if it has been deleted after the move.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Default	Description	Example
`organization_reference`	String	✔		Reference of an organization/company involved in the move (from_organization and/or to_organization)	aEioU123
`job_reference`	String	✔		Reference of a job involved in the move (from_job and/or to_job)	aEioU123
`per_page`	Integer		100	Number of jobs per page
`page`	Integer		1	Page offset

Videos

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

[
  {
    "source": "youtube",
    "external_reference": "1gPC5eOJy8I",
    "name": "The one who started Dribbble with 50 T-shirts",
    "description": "Dan Cederholm is the co-founder of Dribbble, an online community allowing people to showcase their graphic design, web design, illustrations and pictures. He looks back on his career, talking about how he started coding, the challenges he faced at Dribbble as a founder and as a front-end developer, how writing has been the key to his success and much more.",
    "subtitle": "",
    "image": {"url":  "https://cdn.welcometothejungle.co/uploads/article/image/6860/154883/dan-cederholm-dribbble.jpg",
              "small": {"url": "https://cdn.welcometothejungle.co/uploads/article/image/6860/154883/small_dan-cederholm-dribbble.jpg"},
              "thumb": {"url": "https://cdn.welcometothejungle.co/uploads/article/image/6860/154883/thumb_dan-cederholm-dribbble.jpg"}},
    "url": "https://www.youtube.com/watch?v=BMi_rlAnwIg",
    "created_at": "2018-01-15T16:51:20.788757+01:00",
    "updated_at": "2018-12-11T08:35:43.456385+01:00",
    "details": {"snippet":{"title":"The one who started Dribbble with 50 T-shirts","thumbnails":{"standard":{"width":640,"url":"https://i.ytimg.com/vi/BMi_rlAnwIg/sddefault.jpg","height":480},"medium":{"width":320,"url":"https://i.ytimg.com/vi/BMi_rlAnwIg/mqdefault.jpg","height":180},"maxres":{"width":1280,"url":"https://i.ytimg.com/vi/BMi_rlAnwIg/maxresdefault.jpg","height":720},"high":{"width":480,"url":"https://i.ytimg.com/vi/BMi_rlAnwIg/hqdefault.jpg","height":360},"default":{"width":120,"url":"https://i.ytimg.com/vi/BMi_rlAnwIg/default.jpg","height":90}},"tags":["Behind The Code","WTTJ","Welcome to the Jungle","Dribblle","Dan Cederholm"],"publishedAt":"2019-01-30T09:21:57.000Z","localized":{"title":"The one who started Dribbble with 50 T-shirts","description":"Dan Cederholm is the co-founder of Dribbble, an online community allowing people to showcase their graphic design, web design, illustrations and pictures. He looks back on his career, talking about how he started coding, the challenges he faced at Dribbble as a founder and as a front-end developer, how writing has been the key to his success and much more.\n\nhttps://www.welcometothejungle.co/collections/behind-the-code"},"liveBroadcastContent":"none","description":"Dan Cederholm is the co-founder of Dribbble, an online community allowing people to showcase their graphic design, web design, illustrations and pictures. He looks back on his career, talking about how he started coding, the challenges he faced at Dribbble as a founder and as a front-end developer, how writing has been the key to his success and much more.\n\nhttps://www.welcometothejungle.co/collections/behind-the-code","channelTitle":"Welcome to the Jungle Studio","channelId":"UCpJfUQ72fmt4qAbkDvz0iNQ","categoryId":"22"},"kind":"youtube#video","id":"BMi_rlAnwIg","etag":"\"XpPGQXPnxQJhLgs6enD_n8JR4Qk/KjD6f_v7k7xQj4hfzWS1QTXiFWQ\"","contentDetails":{"projection":"rectangular","licensedContent":false,"duration":"PT12M23S","dimension":"2d","definition":"sd","caption":"false"}},
    "reference": "BMi_rlAnwIg"
  },
  ...
]

This endpoint requires videos_r or su_videos_r scope.

This endpoint lets you retrieve your list of videos (scope videos_r) or to all videos (scope su_videos_r). Videos are hosted on Youtube, Dailymotion or 360player (see source and url in the returned body).

The dimensions of each image type are as follows:

“standard” image dimensions fit within 2000x3000 px
“large” image dimensions fit within 1200x2000 px
“medium” image dimensions fit within 850x850 px
“small” image dimensions fit within 650x650 px
“thumb” image dimensions fit within 200x200 px

HTTP Request

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

Query Parameters

Parameter	Type	Required	Default	Description	Example
`organization_reference`	String	✔		Reference of the associated organization/company	aEioU123
`details`	Boolean		false	Return details about the video	true / false
`per_page`	Integer		100	Number of videos per page
`page`	Integer		1	Page offset

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 – Resource 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 maintenance. 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"

[...]
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:

Do not forget to filter your jobs by status (see: ?status=published)
The default “Spontaneous job” is part of the total count.