Job Ads Export Feed

Introduction

Welcome to the API documentation for exporting your job ads. This API allows you to access all the data of your open job ads through a structured JSON feed. You can retrieve your available job ads, gain visibility by publishing your job ads on job sites, and make your integrations with partners easier to manage.

This documentation presents the functional use of the API with the main use cases and the available data.

Quick Start

This section provides an overview to quickly use the API:

Obtain your token

You must have an access token to call the API. It is provided by technical support upon request.

Prerequisites

Access token: required to make the request
Format: the API responses are in JSON format.

Context and use cases

Our API can meet several functional scenarios:

Integration with job boards
- Increase your visibility by simply publishing your job ads.
- We are already integrated with most major job sites.
Integration with a third-party careers site
- Display your job ads on your internal site or your customized careers page outside of Talent Acquisition.
- Highlight some of your job ads or offer your own search engine.
Integration with an internal mobility portal
- Make only your internal job ads visible (detectable via internal_apply_url).
- Easily offer career opportunities to your employees.
Integration with other partner solutions
- Feed tools such as co-opation, onboarding, etc.
- Use the feed as a data source to enrich the candidate experience, for example with a conversational assistant.

API Methods

Access to the JSON feed of job ads

This method allows you to retrieve all open job ads (public and/or internal).

URL:

{url-environnement}/export/job_ads/{token}

Production environment example:

https://app.digitalrecruiters.com/export/job-ads/XXXXXXXLIYEaAqdZyuJGETmR9XX

Expected response

Data format: JSON
Cache: Data is regenerated every 4 hours.

Response structure

{
  "count": <integer>,
  "version": <string>,
  "fetched_at": <string datetime ISO8601>,
  "spontaneousApplyUrl": <object>,
  "ads": <array of ad objects>
}

count: Number of job ads returned.
version: Current version of the API (e.g. "1.0.1").
fetched_at: Date/time of the call.
spontaneousApplyUrl: urlByLang object (see below).
ads: Array of ad objects (the job ads).

Data structure

The following fields are available in the ad object:

Field	Description
locale	ISO code of the job ad language (e.g.: `fr`, `en`).
reference	Unique identifier of the job ad.
published_at	Date the job ad was created.
catch_phrase	Catchphrase of the job ad.
contract_type	Contract type (CDI, CDD, Internship, etc.).
contract_duration	Contract duration (optional) with `min` and `max` (in months).
contract_work_period	Full-time or part-time.
service	Job function associated with the job ad (managed via your internal reference).
service_internal_ref	Internal reference of the job function
service_hash_id	Job function HashId (identifier generated by the platform).
experience_level	Experience level (e.g. "2 to 5 years").
education_level	Minimum degree required (e.g. "Bachelor degree").
title	Title of the job ad.
description	Description of the job ad (HTML possible).
profile	Desired profile (HTML possible).
skills	List of skills.
salary	Salary description (see dedicated structure).
pictures	List of associated images (see dedicated structure).
videos	List of associated videos (video URLs).
internal_apply_url	URL to apply internally (mobility).
apply_url	URL for public application.
address	Job location details (see dedicated structure).
entity	Entity responsible for the job ad (see dedicated structure).
referent_recruiter	Reference recruiter (see dedicated structure).
brand	Associated brand (see dedicated structure).
custom_fields (option)	Custom fields for the job ad.
count_recruited (option)	Number of recruited candidates for the ad (may be absent or `null`).

Structure of a urlByLang object

{
  "fr": <url>
}

each key corresponds to a language (ISO code of the language)
the associated value is the URL for submitting a spontaneous application

Structure of a picture object

{
  "default": <url string>,
  "wide": <url string>
}

default: URL of the image in its original version
wide: URL of the image resized (for wide screen display)

Structure of a salary object

{
 "min": <float>,
 "max": <float>,
 "kind": <string>,
 "rate_type": <string>,
 "variable": <string>,
 "currency": <string>
}

min: minimum salary
max: maximum salary, can be optional if the salary is fixed, in this case only the min value will be provided
kind: type of salary (Hourly, Daily, Monthly, Yearly)
rate_type: Gross or Net
currency: ISO 4217 code (e.g.: EUR / USD / CHF / GBP)
variable: variable part / benefits

Structure of an address node

{
"parts": {
"street": <string>,
"zip": <string>,
"city": <string>,
"county": <string>,
"state": <string>,
"country": <string>
},
"formatted": <string>,
"position": {
"lon": <float>,
"lat": <float>
  }
}

parts: components of the job ad’s address
- street: street/road
- zip: postal code
- city: city
- county: department
- state: region
- country: country
formatted: formatted version of the address (directly usable for display)
position: geographical coordinates of the address
- lon: longitude
- lat: latitude

The “parts” element may contain more or fewer details depending on the address information provided by the user who published the job ad. For example, if the job ad is positioned at the city level, the “Street” field will be returned as null.

Structure of a node_manager_info object

{
  "section_title": <string>, 
  "section_body": <string>, 
  "picture_url": <url string>, 
  "firstname": <string>, 
  "lastname": <string>, 
  "position": <string> 
}

section_title: title of the entity manager's presentation text
section_body: content of the entity manager's presentation text
picture_url: URL of the avatar of the entity manager
firstname: first name of the entity manager
lastname: last name of the entity manager
position: function (job position) of the entity manager

Note These contents are optional, they allow you to work on the company's employer brand

Structure of a node hierarchy

{
 "depth": <integer>,
 "column_name": <string>,
 "public_name": <string>
}

depth: depth of the node in the hierarchy
column_name: name of the column in the hierarchy
public_name: public name of the node

Note Column names are configurable in the hierarchy module by the account administrator. Customized column names begin at depth 3.

column with depth 1: Brand
column with depth 2: Country

Structure of an entity object

{
 "public_name": <string>,
 "around": <string>,
 "internal_ref": <string>,
 "address": <address object>,
 "manager": <node_manager_info object>,
 "hierarchy": <array of node_hierarchy>
}

public_name: public name of the entity
around: description of the surroundings of the entity (contains HTML)
internal_ref: internal reference of the entity if defined (otherwise null)
manager: information about the entity manager
hierarchy: ordered list of the entity’s parent nodes (from the direct parent in the hierarchy up to the ancestor at the “Enseigne” level)

Structure of a referent recruiter object

{
 "firstname": "John",
 "lastname": "Doe",
 "picture_url":
 "https://app.digitalrecruiters.com/generated_contents/images/recru
iter_avatar/FeYb2HCe-John.jpg"
}

firstname: first name of the reference recruiter
lastname: last name of the reference recruiter
picture_url: reference recruiter’s photo (square format 100px by 100px)

Structure of a brand object

{
 "name": "MyBrand",
 "description": "MyBrand is a brand of the MyCompany group present in over 50 countries, launched three years ago and already counting more than 150 clients, including ACME Corporation or Doe & Fils.",
 "logo":
 "https://app.digitalrecruiters.com/generated_contents/images/compa
ny_logo_career/97A6rMjR-brand-logo.png",
 "favicon":
 "https://app.digitalrecruiters.com/generated_contents/images/compa
ny_logo_career/ZeV13K49-brand-favicon.png"
}

name: name of the brand
description: description of the brand
logo: brand logo
favicon: brand favicon

Structure of a custom_fields object

{
 "hash": <hash>,
 "name": <string>,
 "value": <string>,
}

hash: field identifier
name: field name
value: field value (depending on its type, could be empty)
- Yes / No type
- Date type
- Number type
- List type (single or multiple choice)
- Text type

Selecting and filtering job ads

Identifying types of job ads

Internal site: Use only the job ads whose internal_apply_url is not null.
External site: Use only the job ads whose apply_url is not null.

Add #declareStep1 at the end of the URL to automatically redirect to je job ad page with the GDPR pop-up open. (useful if the candidate has already seen the description and wants to apply).

Example:

https://carrieres.mycompany.com/fr/annonce/929019-comptable#declareStep1

Identifying the source of applications

Add ?s_o=NameOfYourSource to track the source in your statistics.

Example:

https://carrieres.mycompany.com/fr/annonce/929019-comptable?s_o=MySite#declareStep1

Additional filtering

When setting up the feed, it is possible to filter job ads according to:

Scope of the hierarchy (e.g. by country or entity).
Type of job function.
Type of contract.
Type of publication (internal, external).

Note: The implementation of these filters is done upstream, through the feed configuration with the technical team. Several feeds can be generated depending on usage.

It is also possible to customize the content returned by the feed:

Displaying custom fields.
Displaying the reference recruiter’s email address.
Displaying the number of recruited candidates.

Full example of a job ad

Below is an example response (with a single job ad returned). The ads field contains an array of similar objects:

{
  "count": 1,
  "version": "1.0.1",
  "fetched_at": "2017-08-08T13:26:46+0200",
  "spontaneousApplyUrl": {
    "fr": "https://carriere.mycompany.com/fr/candidature/spontanee/1#declareStep1"
  },
  "ads": [
    {
      "locale": "fr",
      "reference": "JDMQ528",
      "published_at": "2017-06-26T15:47:14+0200",
      "catch_phrase": "Rejoignez une entreprise ambitieuse !",
      "contract_type": "CDD",
      "contract_duration": {
        "min": "4",
        "max": "12"
      },
      "contract_work_period": "Temps plein",
      "service": "Commercial",
      "experience_level": "De 2 à 5 ans",
      "education_level": "Master, DESS, DEA, Bac+5",
      "title": "Ingénieur commercial H/F",
      "description": "<p>Exemple de description avec HTML</p>",
      "profile": "<p>Profil recherché (HTML autorisé)</p>",
      "skills": [
        "Vente Grands Comptes",
        "Calcul de ROI",
        "Vente consultative"
      ],
      "salary": {
        "min": "2500",
        "max": null,
        "kind": "Mensuel",
        "rate_type": "Brut",
        "variable": "Primes diverses",
        "currency": "EUR"
      },
      "pictures": [
        {
          "default": "https://app.digitalrecruiters.com/...mycompany-68.jpg",
          "wide": "https://app.digitalrecruiters.com/...mycompany-68jpg213254cropped.jpg"
        }
      ],
      "videos": [
        { "url": "https://youtu.be/uNsFDaw2wNc" },
        { "url": "https://youtu.be/XBqX5UMVUno" }
      ],
      "internal_apply_url": "https://carrieres.mycompany.com/s/r9dzV2Rj#declareStep1",
      "apply_url": "https://carrieres.mycompany.com/fr/annonce/4234-commercial-hf-lyon#declareStep1",
      "address": {
        "parts": {
          "street": "34 Avenue Jean Jaurès",
          "zip": "69007",
          "city": "Lyon",
          "county": "Rhône",
          "state": "Auvergne-Rhône-Alpes",
          "country": "France"
        },
        "formatted": "34 Avenue Jean Jaurès, 69007 Lyon, France",
        "position": {
          "lon": "4.84522520",
          "lat": "45.75136290"
        }
      },
      "entity": {
        "public_name": "Commercial",
        "around": "Au cœur de Lyon...",
        "internal_ref": null,
        "address": {
          "parts": {
            "street": "21 Avenue Maréchal de Saxe",
            "zip": "69006",
            "city": "Lyon",
            "county": "Rhône",
            "state": "Auvergne-Rhône-Alpes",
            "country": "France"
          },
          "formatted": "21 Avenue Maréchal de Saxe, 69006 Lyon, France",
          "position": {
            "lon": "4.84459730",
            "lat": "45.76646570"
          }
        },
        "manager": {
          "section_title": "Le mot du manager",
          "section_body": "Rejoindre l'équipe Produits...",
          "picture_url": "https://app.digitalrecruiters.com/...charles.jpg",
          "firstname": "Charles",
          "lastname": "Dupuis",
          "position": "VP Commercial"
        },
        "hierarchy": [
          {
            "depth": 4,
            "column_name": "Villes",
            "public_name": "Lyon"
          },
          {
            "depth": 3,
            "column_name": "Régions",
            "public_name": "Equipe Produits"
          },
          {
            "depth": 2,
            "column_name": "Pays",
            "public_name": "France"
          },
          {
            "depth": 1,
            "column_name": "Enseigne",
            "public_name": "Mycompany"
          }
        ]
      },
      "referent_recruiter": {
        "firstname": "Michel",
        "lastname": "Aufray",
        "picture_url": "https://app.digitalrecruiters.com/...michel.jpg"
      },
      "brand": {
        "name": "MyBrand",
        "description": "Marque du groupe MyCompany présente dans plus de 50 pays...",
        "logo": "https://app.digitalrecruiters.com/...brand-logo.png",
        "favicon": "https://app.digitalrecruiters.com/...brand-favicon.png"
      },
      "custom_fields": [
        {
          "id": "NMAE704",
          "name": "Department",
          "value": "Marketing"
        },
        {
          "id": "XFR321",
          "name": "Comment HR",
          "value": ""
        },
        {
          "id": "JXDP522",
          "name": "Start date",
          "value": "20/03/2021"
        }
      ]
    }
  ]
}

Best practices and additional information

If the token is invalid, you will receive an HTTP error (e.g. 403, 404).
A 4-hour cache is applied when generating the feed. Data changed during this period will only appear in the next cycle.
Don’t forget to add ?s_o=... and #declareStep1 if you want to track the source or display the GDPR pop-up.

Need help? Contact technical support or your Talent Acquisition contact for:

Obtaining or creating a token

Setting up additional or specific feeds

Requesting the activation of filters or options on your feed

Thank you for using the API to export your job ads! We are happy to help you seamlessly integrate your job ads and streamline your recruitment processes.

Introduction​

Quick Start​

Obtain your token​

Prerequisites​

Context and use cases​

API Methods​

Access to the JSON feed of job ads​

Expected response​

Response structure​

Data structure​

Selecting and filtering job ads​

Identifying types of job ads​

Activating the GDPR pop-up​

Identifying the source of applications​

Additional filtering​

Full example of a job ad​

Best practices and additional information​