Skip to main content

Recruited candidates export

Introduction​

Welcome to the API documentation for exporting your recruited candidates. This API allows you to access all your recruited applications data via a structured JSON feed. You can continue your onboarding process and create your new employees outside of Talent Acquisition.

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

Quick Start​

This section provides an overview to quickly use the API:

There are two main ways of retrieving recruited applications:

  • Pull: you query the API yourself on a secure URL via a token.
  • Push: we set up a webhook to directly push the information to the URL of your choice.

Note: The setup of the webhook requires more advanced configuration (error codes validation, retry attempts management, URL security, login/password, etc.).

Obtain your token​

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

Webook configuration​

Setting up the webhook involves more advanced configuration to set up your URL and accesses. See the section Webhook for recruited applications.

In both method you need to contact technical support to activate this API.

Prerequisites​

  • Access token: required to make the request
  • Format: the API responses are in JSON format.
  • URL Webhook: if the push method is implemented.

Context and use cases​

Our API can meet several functional scenarios:

  1. Integration with coreHR
    • Seamlessly transfer new hires’ data (contract details, start dates, etc.) into your core HR.
    • Ensure consistency and accuracy of core HR information to streamline onboarding.
  2. Integration with analytics and BI tools
    • Export recruitment data to your reporting or Business Intelligence solutions.
    • Track key performance indicators, and optimize your hiring process.
  3. Integration with other partner solutions
    • Manage the implementation of your processes with your partners, for example the onboarding of your new employees.

API Methods​

Export of recruited candidates​

This method allows you to export recruited applications that have not yet been exported.

  • URL :

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

  • Production environment example :

    https://app.digitalrecruiters.com/export/hireds/XXXXXXXLIYEaAqdZyuJGETmR9XX

Response structure​

{
  "requested_at": <datetime string>,
  "count": <integer>,
  "remaining": <integer>,
  "hireds": <array of hired object>
}
  • requested_at: Date/time of the call.
  • count: Number of items returned.
  • remaining: Number of items left to export. If this field is 0, it may be absent.
  • hireds: Array of hired objects (see Structure of a hired object).

Tip: To export all recruited candidates, simply query this method as long as remaining is present and not zero.

Export of candidates recruited on a date range​

  • URL : 
    {url-environnement}/export/hireds/{token}/?from=...&to=...

The from and to parameters allow you to export candidates recruited over a specific date range. This allows you to find recruited applications that have already been exported.

  • The default values for from and to are NOW if they are not provided.
  • The format must comply with W3C (ISO 8601).
  • If a timezone is defined, remember to encode the + character (e.g. +01:00 becomes %2B01:00).

Response structure​

{
  "requested_at": <datetime string>,
  "count": <integer>,
  "remaining": <integer>,
  "hireds": <array of hired object>,
  "continue_at": <datetime string>
}
  • requested_at: Date/time of the call.
  • count: Number of items returned.
  • remaining: Number of items left. May be absent if = 0.
  • hireds: Array of hired objects (see below).
  • continue_at: Date to use as the from parameter to continue the export.

Tip: To export all recruited candidates in the date range, make another call by replacing the value of from with the value of continue_at. Repeat until continue_at is no longer present.

Retrieving data from a specific recruited candidate​

  • URL : 
    {url-environnement}/export/hireds/{token}/hired/{hash_application}

This method is used to retrieve detailed information about a recruited candidate via their hash.

Response structure​

{
  "requested_at": <datetime string>,
  "hired": <hired object>
}
  • requested_at: Date/time of the call.
  • hired: hired object (see Structure of a hired object).

Downloading a file​

  • URL : 
    {url-environnement}/export/hireds/{token}/file/{hash}

This method allows you to downlod a file (CV, attachments, etc.) via its hash.

Data recovery (status)​

  • URL : 
    {url-environnement}/export/hireds/{token}/status

This method is used to retrieve general information about the API, in particular the number of applications recruited who have not yet been exported.

Response structure​

{
  "requested_at": <datetime string>,
  "remaining": <integer>
}
  • requested_at: Date/time of the call.
  • remaining: Number of recruited candidates not yet exported.

Data structure​

Structure of a hired object​

{
  "hash": <hash>,
  "title": <string>,
  "contract_type": <string>,
  "created_at": <datetime string>,
  "origin": <string>,
  "recruited_at": <datetime string>,
  "job_accepted_at": <datetime string>,
  "candidate_starting_date": <datetime string>,
  "recruitment_request_author": <recruiter_info>,
  "referent_recruiter": <recruiter_info>,
  "recruited_by": <recruiter_info>,
  "candidate_gender_label": <string>,
  "candidate_first_name": <string>,
  "candidate_last_name": <string>,
  "candidate_address_street": <string>,
  "candidate_address_zip": <string>,
  "candidate_address_city": <string>,
  "candidate_address_country": <string>,
  "candidate_coords_latitude": <float>,
  "candidate_coords_longitude": <float>,
  "candidate_email": <string>,
  "candidate_phone_number": <string>,
  "candidate_website_linkedin": <string>,
  "candidate_website_viadeo": <string>,
  "service_name": <string>,
  "service_internal_ref": <string>,
  "service_hash_id": <string>,
  "job_ad_title": <string>,
  "candidate_languages": <array of string>,
  "candidate_driving_licences": <array of string>,
  "candidate_job_title": <string>,
  "entity": <object entity>,
  "candidate_job_experience_level": <string>,
  "candidate_job_experiences": <array of job_experience>,
  "candidate_skills": <array of string>,
  "candidate_educations": <array of candidate_education>,
  "tags": <array of string>,
  "candidate_message": <string>,
  "cv": <object file>,
  "attached": <array of file>,
  "fields": <array of fields>
}
FieldDescription
hashUnique ID of the recruited application.
job_ad_hash_idUnique ID of the job ad.
titleTitle of the ad for which the application was recruited.
contract_typeType of contract.
created_atDate the application was created.
originSource of the application.
recruited_atDate the recruitment was declared.
job_accepted_atDate the candidate accepted the offer.
candidate_starting_dateHiring date (start date).
recruitment_request_authorRecruiter who initiated the recruitment request.
referent_recruiterLead recruiter of the ad.
recruited_byRecruiter who declared the recruitment.
candidate_gender_labelTitle.
candidate_first_nameCandidate’s first name.
candidate_last_nameCandidate’s last name.
candidate_address_streetStreet address of the candidate.
candidate_address_zipPostal code of the candidate's address.
candidate_address_cityCity of the candidate's address.
candidate_address_countryCountry of the candidate's address.
candidate_coords_latitudeLatitude of the candidate's address.
candidate_coords_longitudeLongitude of the candidate's address.
candidate_emailCandidate’s email.
candidate_phone_numberCandidate’s phone number.
candidate_website_linkedinLink to LinkedIn profile.
candidate_website_viadeoLinks to Viadeo profile.
service_nameName of the job function.
service_internal_refInternal reference of the job function.
service_hash_idUnique ID of the job function.
job_ad_titleTitle of the ad.
candidate_languagesAray of languages spken by the candidate.
candidate_driving_licencesArray of driving licenses.
candidate_job_titleCandidate’s main job.
entityentity object (see Structure of an entity object).
candidate_job_experience_levelCandidate’s overall experience level (e.g. "2 years", "11 months").
candidate_job_experiencesArray of job_experience objects (see below).
candidate_skillsList of the candidate’s skills.
candidate_educationsArray of candidate_education objects.
tagsTags added to the application.
candidate_messageCover letter message.
cvfile object (main resume).
attachedArray of file objects (attachments).
fieldsList of custom fields filled in on an application.
Structure of an entity object

{
  "hash": <hash>,
  "name": <string>,
  "internal_ref": <string>,
  "hierarchy": <array of node_hierarchy>
}
  • hash: Unique ID of the entity.
  • name: Name of the entity.
  • internal_ref: Internal reference(s) of the entity.
  • hierarchy: Ordered list of the entity’s parent nodes (from the direct parent in the tree to the "child account" level ancestor).
Structure of a recruiter_info object

​

{
  "name": <string>,
  "email": <string>
}
  • name: The recruiter’s full name.
  • email: The recruiter’s email address.
Structure of a job_experience object

​

{
  "job_title": <string>,
  "company_name": <string>,
  "place": <string>,
  "date_begin": <datetime string>,
  "date_end": <datetime string|null>,
  "job_experience_level": <string>,
  "mission": <string>,
  "liked": <string>,
  "disliked": <string>
}
  • job_title: Position held.
  • company_name: Company name.
  • place: Location.
  • date_begin / date_end: Start/end dates.
  • job_experience_level: Total duration (e.g. "2 years and 4 months").
  • mission: Description of the tasks.
  • liked: Elements appreciated by the candidate.
  • disliked: Less appreciated elements.
Structure of a candidate_education object

​

{
  "diploma": <string>,
  "establishment": <string>,
  "locality": <string>,
  "duration": <string>,
  "date_begin": <datetime string>,
  "date_end": <datetime string>,
  "specialization": <string>,
  "description": <string>
}
  • diploma: Name of the diploma.
  • establishment: Name of the institution.
  • locality: City or geographical area.
  • duration: Duration (e.g. "2 years and 10 months").
  • date_begin / date_end: Start/end dates.
  • specialization: Specialization.
  • description: Additional details.
Structure of a file object

​

{
  "hash": <hash>,
  "filename": <string>,
  "filesize": <integer>,
  "mime_type": <string>,
  "pdf": <string|false>
}
  • hash: Unique ID of the file.
  • filename: Original file name.
  • filesize: Size in bytes.
  • mime_type: MIME type (e.g. application/pdf).
  • pdf: If a PDF version exists, this field contains the corresponding hash. Otherwise, it is false.
Structure of a fields object

​

{
  "hash": <string>,
  "name": <string>,
  "value": <mixed>
}
  • hash: Unique ID of the custom field.
  • name: Field name.
  • value: The value(s) entered (separated by a comma if multiple).
    Supported type: Yes/NO, Date, Number, List (single or multiple choice), Text.

Webhook of applications recruited​

If the API for recruited applications is active, it is also possible to push the information to a URL provided by the customer. This makes it possible, for example, to manage real time to quickly trigger actions or processes following recruitment in Cegid HR Talent Acquisition.

The data structure is the same as that described above (hired object). The call is made in POST :

{
  "requested_at": <datetime string>,
  "hired": <hired object>
}

To implement this functionality, you need to have :

  • A URL that accepts POST requests.
  • Protect this URL with an authentication mechanism:
    • Basic Auth** (login/password)
    • Token** (token inserted in a custom header)

Return Error Handling :

  • If the HTTP code is < 400, the operation is considered successful. If the HTTP code is >= 400, the operation is considered to have failed. In this case, the system will retry up to 10 times (every 5 minutes by default, configurable).

Example for an exported candidate​

Below is an example of the data returned when an application is exported:

{
  "requested_at": "2017-02-09T15:24:20+01:00",
  "hired": {
    "hash": "5ZmD5NeR",
    "title": "Chef d'équipe H/F",
    "contract_type": "CDI",
    "created_at": "2020-02-09T15:13:32+01:00",
    "origin": "Naturelle",
    "recruited_at": "2020-03-09T15:15:00+01:00",
    "job_accepted_at": "2020-03-08T15:15:00+01:00",
    "candidate_starting_date": "2017-03-14T15:15:00+01:00",
    "recruitment_request_author": {
      "name": "Anne Martin",
      "email": "anne.martin@email.com"
    },
    "referent_recruiter": {
      "name": "Jean Dupont",
      "email": "jean.dupont@email.com"
    },
    "recruited_by": {
      "name": "Marie Dubois",
      "email": "marie.dubois@email.com"
    },
    "job_ad_hash_id": "VVPPPM721",
    "candidate_gender_label": "Monsieur",
    "candidate_first_name": "Julien",
    "candidate_last_name": "Dupont",
    "candidate_address_street": "34 Boulevard Voltaire",
    "candidate_address_zip": "75011",
    "candidate_address_city": "PARIS",
    "candidate_address_country": "France",
    "candidate_email": "julien.dupont@email.com",
    "candidate_phone_number": "061111111",
    "candidate_website_linkedin": "https://linkedin.com/juliendupont",
    "candidate_website_viadeo": "https://viadeo.com/juliendupont",
    "service_name": "Informatique / Systèmes d'information",
    "job_ad_title": "Lead Développeur Full Stack PHP",
    "candidate_languages": [
      "Anglais",
      "Espagnol",
      "Italien"
    ],
    "candidate_driving_licences": [
      "Permis A",
      "Permis B"
    ],
    "candidate_job_title": "Community manager",
    "entity": {
      "hash": "3r9dbaRj",
      "name": "Commercial",
      "internal_ref": "CM 001",
      "hierarchy": [
        {
          "depth": 4,
          "column_name": "Équipes",
          "public_name": "Entité 1"
        },
        {
          "depth": 3,
          "column_name": "Départements",
          "public_name": "Administratif"
        },
        {
          "depth": 2,
          "column_name": "Pays",
          "public_name": "France"
        },
        {
          "depth": 1,
          "column_name": "Compte enfant",
          "public_name": "Entreprise"
        }
      ]
    },
    "candidate_job_experience_level": "3 ans d'expérience",
    "candidate_job_experiences": [
      {
        "job_title": "Community Manager",
        "company_name": "Panasonic",
        "place": "Gennevilliers, France",
        "date_begin": "2012-10-01T00:00:00+02:00",
        "date_end": null,
        "job_experience_level": "4 ans et 5 mois",
        "mission": "Analyse et suivi du Marché...",
        "liked": "J'ai aimé le travail d'équipe...",
        "disliked": "Des contraintes projet parfois compliquées..."
      },
      {
        "job_title": "Assistant Etude de marché",
        "company_name": "Conseil Régional d'Ile de France",
        "place": "Paris Montparnasse, France",
        "date_begin": "2011-05-01T00:00:00+02:00",
        "date_end": "2013-07-31T00:00:00+02:00",
        "job_experience_level": "2 ans et 4 mois",
        "mission": "Analyse de données statistiques...",
        "liked": "J'adore l'analyse statistiques...",
        "disliked": "Les données arrivant parfois au fil de l'eau..."
      }
    ],
    "candidate_skills": [
      "Suite Office",
      "Word",
      "Excel",
      "PowerPoint",
      "Access",
      "IBM",
      "SPSS Statistics 19",
      "Eviews",
      "Vegas Pro 11"
    ],
    "candidate_educations": [
      {
        "diploma": "Master 2 Marketing et Communication",
        "establishment": "Université de Cergy-Pontoise",
        "locality": "Cergy-Pontoise",
        "duration": "6 mois",
        "date_begin": "2013-09-01T00:00:00+02:00",
        "date_end": "2014-02-28T00:00:00+01:00",
        "specialization": "Politique de Produit / Marque...",
        "description": "Filière à forte composante marketing..."
      },
      {
        "diploma": "Licence Gestion de projet en marketing",
        "establishment": "Université de Cergy-Pontoise",
        "locality": "Cergy-Pontoise",
        "duration": "1 an et 10 mois",
        "date_begin": "2011-09-01T00:00:00+02:00",
        "date_end": "2013-06-30T00:00:00+02:00",
        "specialization": "Gestion de projet",
        "description": "Semestre 1 : Général..."
      }
    ],
    "tags": [
      "Marketing direct",
      "Gestion de projet",
      "SEA"
    ],
    "candidate_message": "Bonjour,\n\nVeuillez trouver...",
    "cv": {
      "hash": "ZnqyqKF4",
      "filename": "CV-Maurisson-Nicola.pdf",
      "filesize": "40849",
      "mime_type": "application/pdf",
      "pdf": false
    },
    "attached": [
      {
        "hash": "ZEQwQ2CK",
        "filename": "Lettre-motivation.pdf",
        "filesize": "67840",
        "mime_type": "application/pdf",
        "pdf": false
      }
    ],
    "fields": [
      {
        "hash": "handicapped",
        "name": "Travailleur handicapé",
        "value": "Non"
      },
      {
        "hash": "availability",
        "name": "Disponibilité",
        "value": "Préavis de 3 mois"
      },
      {
        "hash": "current_salary",
        "name": "Salaire actuel",
        "value": "2000 € brut annuel (fixe)\n200 € brut annuel (var.)"
      },
      {
        "hash": "expected_salary",
        "name": "Salaire souhaité",
        "value": "3000 € brut annuel (fixe)\n300 € brut annuel (var.)"
      },
      {
        "hash": "mobility",
        "name": "Mobilité géographique",
        "value": "Paris France, Lyon France"
      },
      {
        "hash": "rRB3eqZm",
        "name": "Liste",
        "value": "Choix 1,Choix 2"
      },
      {
        "hash": "rRy6XPZn",
        "name": "Êtes-vous véhiculé ?",
        "value": "Oui"
      },
      {
        "hash": "WZMMbwZD",
        "name": "Anglais",
        "value": "Oui"
      },
      {
        "hash": "dRjwnNZz",
        "name": "Date",
        "value": "06/07/22"
      }
    ]
  }
}

Best practices and additional information​

  • Data is returned in JSON format.
  • Date fields are provided in W3C (ISO 8601) format.
  • Each response includes a requested_at property corresponding to the date of the call.
  • hash-type fields (unique IDs) contain the characters [a-zA-Z1-9].
  • locale fields follow the format ll_RR (2 letters for the language, 2 letters for the region, e.g. fr_FR).
  • The number of results is limited to 50 items per call.

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

  • Obtaining or creating a token
  • Setting up webhook configuration

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

Summary​

  1. Introduction
  2. API methods
  3. Data structure
  4. Webhook for recruited applications
  5. Example for an exported candidate

Introduction​

Welcome to the API documentation for exporting your recruited candidates. This API allows you to access all your recruited applications data via a structured JSON feed. You can continue your onboarding process and create your new employees outside of Talent Acquisition.

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

Quick Start​

This section provides an overview to quickly use the API:

There are two main ways of retrieving recruited applications:

  • Pull: you query the API yourself on a secure URL via a token.
  • Push: we set up a webhook to directly push the information to the URL of your choice.

Note: The setup of the webhook requires more advanced configuration (error codes validation, retry attempts management, URL security, login/password, etc.).

Obtain your token​

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

Webook configuration​

Setting up the webhook involves more advanced configuration to set up your URL and accesses. See the section. Webhook for recruited applications.

In both method you need to contact technical support to activate this API.

Prerequisites​

  • Access token: required to make the request
  • Cegid HR Talent Acquisition account: not required to use this API, but you must still collaborate with the support team to generate the feed.
  • Format: the API responses are in JSON format.

Context and use cases​

Our API can meet several functional scenarios:

  1. Integration with coreHR
    • Seamlessly transfer new hires’ data (contract details, start dates, etc.) into your coreHR.
    • Ensure consistency and accuracy of core HR information to streamline onboarding.
  2. Integration with analytics and BI tools
    • Export recruitment data to your reporting or Business Intelligence solutions.
    • Track key performance indicators, and optimize your hiring process.
  3. Integration with other partner solutions
    • Manage the implementation of your processes with your partners, for example the onboarding of your new employees.

API Methods​

Export of recruited candidates​

This method allows you to export recruited applications that have not yet been exported.

  • URL :

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

  • Production environment example :

    https://app.digitalrecruiters.com/export/hireds/XXXXXXXLIYEaAqdZyuJGETmR9XX

Response structure​

{
  "requested_at": <datetime string>,
  "count": <integer>,
  "remaining": <integer>,
  "hireds": <array of hired object>
}
  • requested_at: Date/time of the call.
  • count: Number of items returned.
  • remaining: Number of items left to export. If this field is 0, it may be absent.
  • hireds: Array of hired objects (see Structure of a hired object).

Tip: To export all recruited candidates, simply query this method as long as remaining is present and not zero.

Export of candidates recruited on a date range​

  • URL : 
    {url-environnement}/export/hireds/{token}/?from=...&to=...

The from and to parameters allow you to export candidates recruited over a specific date range. This allows you to find recruited applications that have already been exported.

  • The default values for from and to are NOW if they are not supplied.
  • The format must comply with W3C (ISO 8601).
  • If a timezone is defined, remember to encode the + character (e.g. +01:00 becomes %2B01:00).

Response structure​

{
  "requested_at": <datetime string>,
  "count": <integer>,
  "remaining": <integer>,
  "hireds": <array of hired object>,
  "continue_at": <datetime string>
}
  • requested_at: Date/time of the call.
  • count: Number of items returned.
  • remaining: Number of items left. May be absent if = 0.
  • hireds: Array of hired objects (see below).
  • continue_at: Date to use as the from parameter to continue the export.

Tip: To export all recruited candidates in the date range, make another call by replacing the value of from with the value of continue_at. Repeat until continue_at is no longer present.

Retrieving data from a specific recruited candidate​

  • URL : 
    {url-environnement}/export/hireds/{token}/hired/{hash_application}

This method is used to retrieve detailed information about a recruited candidate via their hash.

Response structure​

{
  "requested_at": <datetime string>,
  "hired": <hired object>
}

Downloading a file​

  • URL : 
    {url-environnement}/export/hireds/{token}/file/{hash}

This method allows you to downlod a file (CV, attachments, etc.) via its hash.

Data recovery (status)​

  • URL : 
    {url-environnement}/export/hireds/{token}/status

This method is used to retrieve general information about the API, in particular the number of applications recruited who have not yet been exported.

Response structure​

{
  "requested_at": <datetime string>,
  "remaining": <integer>
}
  • requested_at: Date/time of the call.
  • remaining: Number of recruited candidates not yet exported.

Data structure​

Structure of a hired object​

{
  "hash": <hash>,
  "title": <string>,
  "contract_type": <string>,
  "created_at": <datetime string>,
  "origin": <string>,
  "recruited_at": <datetime string>,
  "job_accepted_at": <datetime string>,
  "candidate_starting_date": <datetime string>,
  "recruitment_request_author": <recruiter_info>,
  "referent_recruiter": <recruiter_info>,
  "recruited_by": <recruiter_info>,
  "candidate_gender_label": <string>,
  "candidate_first_name": <string>,
  "candidate_last_name": <string>,
  "candidate_address_street": <string>,
  "candidate_address_zip": <string>,
  "candidate_address_city": <string>,
  "candidate_address_country": <string>,
  "candidate_coords_latitude": <float>,
  "candidate_coords_longitude": <float>,
  "candidate_email": <string>,
  "candidate_phone_number": <string>,
  "candidate_website_linkedin": <string>,
  "candidate_website_viadeo": <string>,
  "service_name": <string>,
  "service_internal_ref": <string>,
  "service_hash_id": <string>,
  "job_ad_title": <string>,
  "candidate_languages": <array of string>,
  "candidate_driving_licences": <array of string>,
  "candidate_job_title": <string>,
  "entity": <object entity>,
  "candidate_job_experience_level": <string>,
  "candidate_job_experiences": <array of job_experience>,
  "candidate_skills": <array of string>,
  "candidate_educations": <array of candidate_education>,
  "tags": <array of string>,
  "candidate_message": <string>,
  "cv": <object file>,
  "attached": <array of file>,
  "fields": <array of fields>
}
FieldDescription
hashUnique ID of the recruited candidate.
job_ad_hash_idUnique ID of the job ad.
titleTitle of the ad for which the application was recruited.
contract_typeType of contract.
created_atDate the application was created.
originSource of the application.
recruited_atDate the recruitment was declared.
job_accepted_atDate the candidate accepted the offer.
candidate_starting_dateHiring date (start date).
recruitment_request_authorRecruiter who initiated the recruitment request.
referent_recruiterLead recruiter of the ad.
recruited_byRecruiter who declared the recruitment.
candidate_gender_labelTitle.
candidate_first_nameCandidate’s first name.
candidate_last_nameCandidate’s last name.
candidate_address_streetStreet address of the candidate.
candidate_address_zipPostal code of the candidate's address.
candidate_address_cityCity of the candidate's address.
candidate_address_countryCountry of the candidate's address.
candidate_coords_latitudeLatitude of the candidate's address.
candidate_coords_longitudeLongitude of the candidate's address.
candidate_emailCandidate’s email.
candidate_phone_numberCandidate’s phone number.
candidate_website_linkedinLink to LinkedIn profile.
candidate_website_viadeoLinks to Viadeo profile.
service_nameName of the service/business.
service_internal_refInternal reference of the job (filled via the job reference manager).
service_hash_idUnique ID of the service.
job_ad_titleTitle of the ad.
candidate_languagesAray of languages spken by the candidate.
candidate_driving_licencesArray of driving licenses.
candidate_job_titleCandidate’s main job.
entityentity object (see Structure of an entity object).
candidate_job_experience_levelCandidate’s overall experience level (e.g. "2 years", "11 months").
candidate_job_experiencesArray of job_experience objects (see below).
candidate_skillsList of the candidate’s skills.
candidate_educationsArray of candidate_education objects.
tagsTags added to the application.
candidate_messageCover letter message.
cvfile object (main resume).
attachedArray of file objects (attachments).
fieldsList of custom fields filled in on an application.
Structure of an entity object

​

{
  "hash": <hash>,
  "name": <string>,
  "internal_ref": <string>,
  "hierarchy": <array of node_hierarchy>
}
  • hash: Unique ID of the entity.
  • name: Name of the entity.
  • internal_ref: Internal reference(s) of the entity.
  • hierarchy: Ordered list of the entity’s parent nodes.
Structure of a recruiter_info object

​

{
  "name": <string>,
  "email": <string>
}
  • name: The recruiter’s full name.
  • email: The recruiter’s email address.
Structure of a job_experience object

​

{
  "job_title": <string>,
  "company_name": <string>,
  "place": <string>,
  "date_begin": <datetime string>,
  "date_end": <datetime string|null>,
  "job_experience_level": <string>,
  "mission": <string>,
  "liked": <string>,
  "disliked": <string>
}
  • job_title: Position held.
  • company_name: Company name.
  • place: Location.
  • date_begin / date_end: Start/end dates.
  • job_experience_level: Total duration (e.g. "2 years and 4 months").
  • mission: Description of the tasks.
  • liked: Elements appreciated by the candidate.
  • disliked: Less appreciated elements.
Structure of a candidate_education object

​

{
  "diploma": <string>,
  "establishment": <string>,
  "locality": <string>,
  "duration": <string>,
  "date_begin": <datetime string>,
  "date_end": <datetime string>,
  "specialization": <string>,
  "description": <string>
}
  • diploma: Name of the diploma.
  • establishment: Name of the institution.
  • locality: City or geographical area.
  • duration: Duration (e.g. "2 years and 10 months").
  • date_begin / date_end: Start/end dates.
  • specialization: Specialization.
  • description: Additional details.
Structure of a file object

​

{
  "hash": <hash>,
  "filename": <string>,
  "filesize": <integer>,
  "mime_type": <string>,
  "pdf": <string|false>
}
  • hash: Unique ID of the file.
  • filename: Original file name.
  • filesize: Size in bytes.
  • mime_type: MIME type (e.g. application/pdf).
  • pdf: If a PDF version exists, this field contains the corresponding hash. Otherwise, it is false.
Structure of a fields object

​

{
  "hash": <string>,
  "name": <string>,
  "value": <mixed>
}
  • hash: Unique ID of the custom field.
  • name: Field name.
  • value: The value(s) entered (separated by a comma if multiple).
    Supported type: Yes/NO, Date, Number, List (single or multiple choise, Text

Webhook of applications recruited​

If the API for recruited applications is active, it is also possible to push the information to a URL provided by the customer. This makes it possible, for example, to manage real time to quickly trigger actions or processes following recruitment in Cegid HR Talent Acquisition.

The data structure is the same as that described above (hired object). The call is made in POST :

{
  "requested_at": <datetime string>,
  "hired": <hired object>
}

To implement this functionality, you need to have :

  • A URL that accepts POST requests.
  • Protect this URL with an authentication mechanism:
    • Basic Auth** (login/password)
    • Token** (token inserted in a custom header)

Return Error Handling :

  • If the HTTP code is < 400, the operation is considered successful. If the HTTP code is >= 400, the operation is considered to have failed. In this case, the system will retry up to 10 times (every 5 minutes by default, configurable).

Example for an exported candidate​

Below is an example of the data returned when an application is exported:

{
  "requested_at": "2017-02-09T15:24:20+01:00",
  "hired": {
    "hash": "5ZmD5NeR",
    "title": "Chef d'équipe H/F",
    "contract_type": "CDI",
    "created_at": "2020-02-09T15:13:32+01:00",
    "origin": "Naturelle",
    "recruited_at": "2020-03-09T15:15:00+01:00",
    "job_accepted_at": "2020-03-08T15:15:00+01:00",
    "candidate_starting_date": "2017-03-14T15:15:00+01:00",
    "recruitment_request_author": {
      "name": "Anne Martin",
      "email": "anne.martin@email.com"
    },
    "referent_recruiter": {
      "name": "Jean Dupont",
      "email": "jean.dupont@email.com"
    },
    "recruited_by": {
      "name": "Marie Dubois",
      "email": "marie.dubois@email.com"
    },
    "job_ad_hash_id": "VVPPPM721",
    "candidate_gender_label": "Monsieur",
    "candidate_first_name": "Julien",
    "candidate_last_name": "Dupont",
    "candidate_address_street": "34 Boulevard Voltaire",
    "candidate_address_zip": "75011",
    "candidate_address_city": "PARIS",
    "candidate_address_country": "France",
    "candidate_email": "julien.dupont@gmail.com",
    "candidate_phone_number": "0613422439",
    "candidate_website_linkedin": "https://linkedin.com/juliendupont",
    "candidate_website_viadeo": "https://viadeo.com/juliendupont",
    "service_name": "Informatique / Systèmes d'information",
    "job_ad_title": "Lead Développeur Full Stack PHP",
    "candidate_languages": [
      "Anglais",
      "Espagnol",
      "Italien"
    ],
    "candidate_driving_licences": [
      "Permis A",
      "Permis B"
    ],
    "candidate_job_title": "Community manager",
    "entity": {
      "hash": "3r9dbaRj",
      "name": "Commercial",
      "internal_ref": "CM 001",
      "hierarchy": [
        {
          "depth": 4,
          "column_name": "Équipes",
          "public_name": "Entité 1"
        },
        {
          "depth": 3,
          "column_name": "Départements",
          "public_name": "Administratif"
        },
        {
          "depth": 2,
          "column_name": "Pays",
          "public_name": "France"
        },
        {
          "depth": 1,
          "column_name": "Compte enfant",
          "public_name": "Entreprise"
        }
      ]
    },
    "candidate_job_experience_level": "3 ans d'expérience",
    "candidate_job_experiences": [
      {
        "job_title": "Community Manager",
        "company_name": "Panasonic",
        "place": "Gennevilliers, France",
        "date_begin": "2012-10-01T00:00:00+02:00",
        "date_end": null,
        "job_experience_level": "4 ans et 5 mois",
        "mission": "Analyse et suivi du Marché...",
        "liked": "J'ai aimé le travail d'équipe...",
        "disliked": "Des contraintes projet parfois compliquées..."
      },
      {
        "job_title": "Assistant Etude de marché",
        "company_name": "Conseil Régional d'Ile de France",
        "place": "Paris Montparnasse, France",
        "date_begin": "2011-05-01T00:00:00+02:00",
        "date_end": "2013-07-31T00:00:00+02:00",
        "job_experience_level": "2 ans et 4 mois",
        "mission": "Analyse de données statistiques...",
        "liked": "J'adore l'analyse statistiques...",
        "disliked": "Les données arrivant parfois au fil de l'eau..."
      }
    ],
    "candidate_skills": [
      "Suite Office",
      "Word",
      "Excel",
      "PowerPoint",
      "Access",
      "IBM",
      "SPSS Statistics 19",
      "Eviews",
      "Vegas Pro 11"
    ],
    "candidate_educations": [
      {
        "diploma": "Master 2 Marketing et Communication",
        "establishment": "Université de Cergy-Pontoise",
        "locality": "Cergy-Pontoise",
        "duration": "6 mois",
        "date_begin": "2013-09-01T00:00:00+02:00",
        "date_end": "2014-02-28T00:00:00+01:00",
        "specialization": "Politique de Produit / Marque...",
        "description": "Filière à forte composante marketing..."
      },
      {
        "diploma": "Licence Gestion de projet en marketing",
        "establishment": "Université de Cergy-Pontoise",
        "locality": "Cergy-Pontoise",
        "duration": "1 an et 10 mois",
        "date_begin": "2011-09-01T00:00:00+02:00",
        "date_end": "2013-06-30T00:00:00+02:00",
        "specialization": "Gestion de projet",
        "description": "Semestre 1 : Général..."
      }
    ],
    "tags": [
      "Marketing direct",
      "Gestion de projet",
      "SEA"
    ],
    "candidate_message": "Bonjour,\n\nVeuillez trouver...",
    "cv": {
      "hash": "ZnqyqKF4",
      "filename": "CV-Maurisson-Nicola.pdf",
      "filesize": "40849",
      "mime_type": "application/pdf",
      "pdf": false
    },
    "attached": [
      {
        "hash": "ZEQwQ2CK",
        "filename": "Lettre-motivation.pdf",
        "filesize": "67840",
        "mime_type": "application/pdf",
        "pdf": false
      }
    ],
    "fields": [
      {
        "hash": "handicapped",
        "name": "Travailleur handicapé",
        "value": "Non"
      },
      {
        "hash": "availability",
        "name": "Disponibilité",
        "value": "Préavis de 3 mois"
      },
      {
        "hash": "current_salary",
        "name": "Salaire actuel",
        "value": "2000 € brut annuel (fixe)\n200 € brut annuel (var.)"
      },
      {
        "hash": "expected_salary",
        "name": "Salaire souhaité",
        "value": "3000 € brut annuel (fixe)\n300 € brut annuel (var.)"
      },
      {
        "hash": "mobility",
        "name": "Mobilité géographique",
        "value": "Paris France, Lyon France"
      },
      {
        "hash": "rRB3eqZm",
        "name": "Liste",
        "value": "Choix 1,Choix 2"
      },
      {
        "hash": "rRy6XPZn",
        "name": "Êtes-vous véhiculé ?",
        "value": "Oui"
      },
      {
        "hash": "WZMMbwZD",
        "name": "Anglais",
        "value": "Oui"
      },
      {
        "hash": "dRjwnNZz",
        "name": "Date",
        "value": "06/07/22"
      }
    ]
  }
}

Best practices and additional information​

  • Data is returned in JSON format.
  • Date fields are provided in W3C (ISO 8601) format.
  • Each response includes a requested_at property corresponding to the date of the call.
  • hash-type fields (unique IDs) contain the characters [a-zA-Z1-9].
  • locale fields follow the format ll_RR (2 letters for the language, 2 letters for the region, e.g. fr_FR).
  • The number of results is limited to 50 items per call.

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

  • Obtaining or creating a token
  • Setting up webhook configuration

Thank you for using the Export of recruited candidates API! We hope this documentation will help you effectively integrate the necessary data into your HR processes. Do not hesitate to contact us for any assistance or additional setup.