Import job applications

Introduction

Welcome to the API documentation for importing job applications. This API allows you to create applications in a specific job ads. It also tracks the status of the application and the history of status changes in Talent Acquisition.

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

Prerequisites

Access token: required to make the request
Format: Send data in JSON format.

Context and use cases

Our API can meet several functional scenarios:

Integration with a third-party careers site
- Manage your own application process without redirecting the candidate to Talent Aquisition's process
- Direct apply and send candidate to our Talent Acquisition account
Integration with partner job portal
- Allow job site to use this API to bypass the personalised experience you have configured for each of your ads
- No longer redirect candidate to your career site and let the partner manage the application process
Integration with co-optation partners
- Import your talent, track progress through to recruitment
- Manage your co-optations with your partners
Import applications from your former ATS
- Bulk import of you applications Data
- Contact our technical team to ensure performance based on data volume

Important: you need to specified a job ad to import your application. You can't add a application in your candidate pool.

API Methods

Creating an Application into a job ad

HTTP method: 'POST'

This method allows you to create applications for an ad by submitting data directly into the call AND/OR by sending a file containing the application information (CV). Cegid HR Talent Acquisition then extracts the information from the file, which will be available on the form created for the application.

URL:

{url-environment}/api/candidate/apply/{token}

Production environment example:

https://app.digitalrecruiters.com/api/candidate/apply/XXXXXXXLIYEaAqdZyuJETmR9XX

Structure of the Call

{
  "version": "<string>",
  "consent_date": "<date>",
  "s_o": "<string>",
  "locale": "<string>",
  "ApplicationMessage": "<object message>",
  "ApplicationProfile": "<object application profile>",
  "file": "<object file>"
}

reference(required): Unique reference of the ad (7 characters).
consent_date(required): Applicant's consent date in YYYY-mm-dd format.
s_o(required): Origin of the application (255 characters maximum).
locale(required): Location of the applicant, including the language for exchanges (5 characters).

Attention: Required fields contained in the ApplicationProfile may not be provided, provided that they can be extracted from the file. If the mandatory fields contained in the ApplicationProfile object are provided AND these fields are also extracted from the file, then the ApplicationProfile fields will be taken into account (instead of those extracted from the provided file). The ad reference can be obtained from your account or from the API Job Ad Export Feed.

Structure of the Response

Success:
- 201: Creation successful, all data retrieved.
- 202: Creation successful but missing information.

More details are provided in the body of the response:

{
  "hash": "<string>",
  "message": "<string>"
}

hash: Hash of the application created
message: Error messages

Structure of the Response in case of error

The response consists of an HTTP code (400, bad request or 500 internal error) as appropriate. More details are provided in the body of the response:

{
  "code": "<integer>",
  "message": "<array>"
}

code: Error code
message: Table containing the error message(s)

Error codes are referenced in the section 'Error codes'.

Monitoring the Status of an Application (option)

HTTP Method: GET

View the current stage and status of an application imported via the Application Import API.

URL:

{url-environment}/api/candidate/status/{token}/{hash}

Production environment example:

https://app.digitalrecruiters.com/api/candidate/status/XXXXXXXLIYEaAqdZyuJETmR9XX/xxxxHeu6Z3

Structure of the Response

{
  "version": "<string>",
  "fetched_at": "<date>",
  "data": {
    "hash": "<hash>",
    "state": "<string>",
    "imported_at": "<date>",
    "last_step": "<object candidate status>",
    "history_steps": [
      "<object candidate status>"
    ]
  }
}

version: version of the API
fetched_at: Date of API call
hash: Hash of the requested application (255 characters maximum)
state: status of the application. this field can have the following values:
- active (the application is active)
- anonymized (the application has been anonymized)
- deleted (application has been deleted)
imported_at: date the application was imported into Talent Acquisition
last_step: the current step the application is at
history_steps: history of application step changes

Structure of the candidate status object

{
    "level_labels": [
<locale> : <string>
    ],
    "step_labels": [
<locale> : <string>
    ]
}

level_labels: table with the name of the status of the application in the locales available for the account.
step_labels: table with the name of the application step in the locales available for the account. This field is null for the levels: Application / Recruitment / Withdrawn / Refusal

Data Structure

Object Application Message

{
  "message": "<string>"
}

message: Optionnal message from the candidate

Object Application Profile

{
  "gender": "<integer>",
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "<string>",
  "phoneNumber": "<string>",
  "job": "<string>",
  "addressStreet": "<string>",
  "addressZip": "<string>",
  "addressCity": "<string>"
}

Field	Required	Description	Max Length
gender	Yes (can be taken from the file)	Candidate’s gender (1 = male, 2 = female)	-
firstName	Yes (can be taken from the file)	Candidate’s first name	255
lastName	Yes (can be taken from the file)	Candidate’s last name	255
email	Yes (can be taken from the file)	Candidate’s email address (used for communication)	255
phoneNumber	No (can be taken from the file)	Candidate’s phone number in international format (e.g., +44XXXXXXXXX or 0044)	255
job	No (can be taken from the file)	Candidate’s job title	255
addressStreet	No (can be taken from the file)	Candidate’s street address	255
addressZip	No (can be taken from the file)	Candidate’s ZIP code	255
addressCity	No (can be taken from the file)	Candidate’s city	255

Object File

{
  "content": "<string>",
  "name": "<string>"
}

content: Base64 encoed file
file.name: Name of the file (255 characters)

Error Codes

Code	Cause
1000	Invalid token or insufficient rights
1001	Error validating sent data
1011	File upload failed
1012	File too large (limited to 8MB)
1090	Advertisement reference not determined
1091	Invalid application hash
1777	Unexpected error

Example Application Import

{
  "reference": "5ZmXLGnX",
  "consent_date": "2019-02-07 00:00:00",
  "s_o": "API origin",
  "locale": "fr_FR",
  "ApplicationMessage": {
    "message": "message du candidat"
  },
  "ApplicationProfile": {
    "gender": 2,
    "firstName": "Sandrine",
    "lastName": "Franches",
    "email": "sandrine@yopmail.com",
    "phoneNumber": "0611111111",
    "job": "Webmarketing Project Manager",
    "addressStreet": "10 boulevard Jean Jaures",
    "addressZip": "75014",
    "addressCity": "Paris"
  },
  "file": {
    "content": "UESDBBQABgAIAAAAIQCHKywEaQEAAIcFAAATAAgC...(base 64 encoded file)",
    "name": "Sandrine-Franches.docx"
  }
}

Example Application Status

{
  "version": "1.0.1",
  "fetched_at": "2019-07-19T07:46:22+00:00",
  "data": {
    "hash": "RG1654v9",
    "state": "active",
    "imported_at": "2019-07-19 09:44:43",
    "current_step": {
      "level_labels": {
        "en_FR": "Proposition",
        "en_GB": "Offer",
        "es_ES": "Propuesta"
      },
      "step_labels": {
        "en_GB": "Offer",
        "es_ES": "Propuesta",
        "en_FR": "Proposal"
      },
      "created_at": "2019-07-19 09:45:38"
    },
    "history_steps": [
      {
        "level_labels": {
          "en_FR": "Proposal",
          "en_GB": "Offer",
          "es_ES": "Propuesta"
        },
        "step_labels": {
          "en_GB": "Offer",
          "es_ES": "Propuesta",
          "en_FR": "Proposal"
        },
        "created_at": "2019-07-19 09:45:38"
      },
      {
        "level_labels": {
          "en_FR": "Qualification",
          "en_GB": "Qualification",
          "es_ES": "Cualificación"
        },
        "step_labels": {
          "en_GB": "Qualification",
          "es_ES": "Cualificación",
          "en_GB": "Qualification"
        },
        "created_at": "2019-07-19 09:45:19"
      },
      {
        "level_labels": {
          "en_GB": "Preselection",
          "en_GB": "Preselection",
          "es_ES": "Preselección"
        },
        "step_labels": {
          "en_FR": "Preselection 2"
        },
        "created_at": "2019-07-19 09:45:17"
      },
      {
        "level_labels": {
          "en_FR": "Preselection",
          "en_GB": "Preselection",
          "es_ES": "Preselección"
        },
        "step_labels": {
          "en_GB": "Preselection",
          "es_ES": "Preselección",
          "fr_FR": "Preselection"
        },
        "created_at": "2019-07-19 09:45:14"
      },
      {
        "level_labels": {
          "fr_FR": "Candidature",
          "en_GB": "Application",
          "es_ES": "Candidatura"
        },
        "step_labels": null,
        "created_at": "2019-07-19 09:44:43"
      }
    ]
  }
}

Best practices and additional information

The data is formatted in JSON
Date field are provided in W3C (ISO 8601) format: https://www.w3.org/TR/NOTE-datetime
The hash fields (unique identifiers) can contgain the following characters: [a-zA-Z1-9]
If you need to integrate a large volume of data, please contact the support team beforehand.

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

Obtaining or creating a token

Bulk import applications

Thank you for using the API to import a job application! We are happy to help you seamlessly integrate your job applications and streamline your recruitment processes.

Summary

Introduction
Quick Start (Guide de démarrage)
Prerequisites
Context and use cases
API Methods
- Access to the JSON feed of job ads
- Response structure
Data structure
Selecting and filtering job ads
Full example of a job ad
Best practices and additional information
Next steps

Introduction

Welcome to the API documentation for importing an application. This API allows you to create applications in a specific job ads. It also tracks the status of the application and the history of status changes in Talent Acquisition.

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.

Make a first call

curl -X POST {url-environnement}/api/candidate/apply/{token}

Production environment example:

curl -X POST https://app.digitalrecruiters.com/api/candidate/apply/XXXXXXXLIYEaAqdZyuJGETmR9XX

Including the body with the applications data (see below)

Analyze the response

You will get a response code of 201 or 202. This means that your application has been created successfully!

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: Send data in JSON format.

Context and use cases

Our API can meet several functional scenarios:

Integration with a third-party careers site
- Manage your own application process without redirecting the candidate to Talent Aquisition's process
- Direct apply and send candidate to our Talent Acquisition account
Integration with partner job portal
- Allow job site to use this API to bypass the personalised experience you have configured for each of your ads
- No longer redirect candidate to your career site and let the partner manage the application process
Integration with cooptation partners
- Import your talent, track progress through to recruitment
- Manage your co-optations with your partners
Import applications from your former ATS
- Bulk import of you applications Data
- Contact our technical team to ensure performance based on data volume

Important: you need to specified a job ad to import your application. You can't add a application in your candidate pool.

API Methods

Creating an Application into a job ad

HTTP method: 'POST'

URL:

{url-environment}/api/candidate/apply/{token}

Production environment example:

https://app.digitalrecruiters.com/api/candidate/apply/XXXXXXXLIYEaAqdZyuJETmR9XX

Structure of the Call

{
  "version": "<string>",
  "consent_date": "<date>",
  "s_o": "<string>",
  "locale": "<string>",
  "ApplicationMessage": "<object message>",
  "ApplicationProfile": "<object application profile>",
  "file": "<object file>"
}

reference(required): Unique reference of the ad (7 characters).
consent_date(required): Applicant's consent date in YYYY-mm-dd format.
s_o(required): Origin of the application (255 characters maximum).
locale(required): Location of the applicant, including the language for exchanges (5 characters).

Attention: Required fields contained in the ApplicationProfile may not be provided, provided that they can be extracted from the file. If the mandatory fields contained in the ApplicationProfile object are provided AND these fields are also extracted from the file, then the ApplicationProfile fields will be taken into account (instead of those extracted from the provided file). The ad reference can be obtained from the application or from the ad export stream (access available on request).

Structure of the Response

Success:
- 201: Creation successful, all data retrieved.
- 202: Creation successful but missing information.

More details are provided in the body of the response:

{
  "hash": "<string>",
  "message": "<string>"
}

hash: Hash of the application created
message: Error messages

Structure of the Response in case of error

The response consists of an HTTP code (400, bad request or 500 internal error) as appropriate. More details are provided in the body of the response:

{
  "code": "<integer>",
  "message": "<array>"
}

code: Error code
message: Table containing the error message(s)

Error codes are referenced in the section 'Error codes'.

Monitoring the Status of an Application

HTTP Method: GET

View the current stage and status of an application imported via the Application Import API.

URL:

{url-environment}/api/candidate/status/{token}/{hash}

Production environment example:

https://app.digitalrecruiters.com/api/candidate/status/XXXXXXXLIYEaAqdZyuJETmR9XX/xxxxHeu6Z3

Structure of the Response

{
  "version": "<string>",
  "fetched_at": "<date>",
  "data": {
    "hash": "<hash>",
    "state": "<string>",
    "imported_at": "<date>",
    "last_step": "<object candidate status>",
    "history_steps": [
      "<object candidate status>"
    ]
  }
}

version: version of the API
fetched_at: Date of API call
hash: Hash of the requested application (255 characters maximum)
state: status of the application. this field can have the following values:
- active (the application is active)
- anonymized (the application has been anonymized)
- deleted (application has been deleted)
imported_at: date the application was imported into Talent Acquisition
last_step: the current step the application is at
history_steps: history of application step changes

Structure of the candidate status object

{
    "level_labels": [
<locale> : <string>
    ],
    "step_labels": [
<locale> : <string>
    ]
}

level_labels: table with the name of the status of the application in the locales available for the account.
step_labels: table with the name of the application step in the locales available for the account. This field is null for the levels: Application / Recruitment / Withdrawn / Refusal

Data Structure

Object Application Message

{
  "message": "<string>"
}

message: Optionnal message from the candidate

Object Application Profile

{
  "gender": "<integer>",
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "<string>",
  "phoneNumber": "<string>",
  "job": "<string>",
  "addressStreet": "<string>",
  "addressZip": "<string>",
  "addressCity": "<string>"
}

Field	Required	Description	Max Length
gender	Yes (can be taken from the file)	Candidate’s gender (1 = male, 2 = female)	-
firstName	Yes (can be taken from the file)	Candidate’s first name	255
lastName	Yes (can be taken from the file)	Candidate’s last name	255
email	Yes (can be taken from the file)	Candidate’s email address (used for communication)	255
phoneNumber	No (can be taken from the file)	Candidate’s phone number in international format (e.g., +44XXXXXXXXX or 0044)	255
job	No (can be taken from the file)	Candidate’s job title	255
addressStreet	No (can be taken from the file)	Candidate’s street address	255
addressZip	No (can be taken from the file)	Candidate’s ZIP code	255
addressCity	No (can be taken from the file)	Candidate’s city	255

Object File

{
  "content": "<string>",
  "name": "<string>"
}

content: Base64 encoed file
file.name: Name of the file (255 characters)

Error Codes

Code	Cause
1000	Invalid token or insufficient rights
1001	Error validating sent data
1011	File upload failed
1012	File too large (limited to 8MB)
1090	Advertisement reference not determined
1091	Invalid application hash
1777	Unexpected error

Example Application Import

{
  "reference": "5ZmXLGnX",
  "consent_date": "2019-02-07 00:00:00",
  "s_o": "API origin",
  "locale": "fr_FR",
  "ApplicationMessage": {
    "message": "message du candidat"
  },
  "ApplicationProfile": {
    "gender": 2,
    "firstName": "Sandrine",
    "lastName": "Franches",
    "email": "sandrine@yopmail.com",
    "phoneNumber": "0619192992",
    "job": "Webmarketing Project Manager",
    "addressStreet": "45 boulevard Jourdan",
    "addressZip": "75014",
    "addressCity": "Paris"
  },
  "file": {
    "content": "UESDBBQABgAIAAAAIQCHKywEaQEAAIcFAAATAAgC...(base 64 encoded file)",
    "name": "Sandrine-Franches.docx"
  }
}

Example Application Status

{
  "version": "1.0.1",
  "fetched_at": "2019-07-19T07:46:22+00:00",
  "data": {
    "hash": "RG1654v9",
    "state": "active",
    "imported_at": "2019-07-19 09:44:43",
    "current_step": {
      "level_labels": {
        "en_FR": "Proposition",
        "en_GB": "Offer",
        "es_ES": "Propuesta"
      },
      "step_labels": {
        "en_GB": "Offer",
        "es_ES": "Propuesta",
        "en_FR": "Proposal"
      },
      "created_at": "2019-07-19 09:45:38"
    },
    "history_steps": [
      {
        "level_labels": {
          "en_FR": "Proposal",
          "en_GB": "Offer",
          "es_ES": "Propuesta"
        },
        "step_labels": {
          "en_GB": "Offer",
          "es_ES": "Propuesta",
          "en_FR": "Proposal"
        },
        "created_at": "2019-07-19 09:45:38"
      },
      {
        "level_labels": {
          "en_FR": "Qualification",
          "en_GB": "Qualification",
          "es_ES": "Cualificación"
        },
        "step_labels": {
          "en_GB": "Qualification",
          "es_ES": "Cualificación",
          "en_GB": "Qualification"
        },
        "created_at": "2019-07-19 09:45:19"
      },
      {
        "level_labels": {
          "en_GB": "Preselection",
          "en_GB": "Preselection",
          "es_ES": "Preselección"
        },
        "step_labels": {
          "en_FR": "Preselection 2"
        },
        "created_at": "2019-07-19 09:45:17"
      },
      {
        "level_labels": {
          "en_FR": "Preselection",
          "en_GB": "Preselection",
          "es_ES": "Preselección"
        },
        "step_labels": {
          "en_GB": "Preselection",
          "es_ES": "Preselección",
          "fr_FR": "Preselection"
        },
        "created_at": "2019-07-19 09:45:14"
      },
      {
        "level_labels": {
          "fr_FR": "Candidature",
          "en_GB": "Application",
          "es_ES": "Candidatura"
        },
        "step_labels": null,
        "created_at": "2019-07-19 09:44:43"
      }
    ]
  }
}

Best practices and additional information

The data is formatted in JSON
Date field are provided in W3C (ISO 8601) format: https://www.w3.org/TR/NOTE-datetime
The hash fields (unique identifiers) can contgain the following characters: [a-zA-Z1-9]

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

Obtaining or creating a token

Bulk import applications

Thank you for using the API to import a job application! We are happy to help you seamlessly integrate your job offers and streamline your recruitment processes.

Introduction​

Prerequisites​

Context and use cases​

API Methods​

Creating an Application into a job ad​

Structure of the Call​

Structure of the Response​

Structure of the Response in case of error​

Monitoring the Status of an Application (option)​

Structure of the Response​

Structure of the candidate status object​

Data Structure​

Object Application Message​

Object Application Profile​

Object File​

Error Codes​

Example Application Import​

Example Application Status​

Best practices and additional information​

Summary​

Introduction​

Quick Start​

Obtain your token​

Make a first call​

Analyze the response​

Prerequisites​

Context and use cases​

API Methods​

Creating an Application into a job ad​

Structure of the Call​

Structure of the Response​

Structure of the Response in case of error​

Monitoring the Status of an Application​

Structure of the Response​

Structure of the candidate status object​

Data Structure​

Object Application Message​

Object Application Profile​

Object File​

Error Codes​

Example Application Import​

Example Application Status​

Best practices and additional information​

Introduction

Prerequisites

Context and use cases

API Methods

Creating an Application into a job ad

Structure of the Call

Structure of the Response

Structure of the Response in case of error

Monitoring the Status of an Application (option)

Structure of the Response

Structure of the candidate status object

Data Structure

Object Application Message

Object Application Profile

Object File

Error Codes

Example Application Import

Example Application Status

Best practices and additional information

Summary

Introduction

Quick Start

Obtain your token

Make a first call

Analyze the response

Prerequisites

Context and use cases

API Methods

Creating an Application into a job ad

Structure of the Call

Structure of the Response

Structure of the Response in case of error

Monitoring the Status of an Application

Structure of the Response

Structure of the candidate status object

Data Structure

Object Application Message

Object Application Profile

Object File

Error Codes

Example Application Import

Example Application Status

Best practices and additional information