Job Details Service

Job details service is expected to return the following information about the job: its status (ACTIVE or EXPIRED) and screening questions. The service will be called before an application process.

The endpoint URL must be sent to the ATSi Apply team in advance so it can be configured.

Endpoint requirements:

  • use HTTPS protocol to ensure safe transfer of data
  • be accessible from the Internet
  • only accept requests from ATSi Apply live servers (IPs will be provided during the implementation process)
  • ATS should expose a single endpoint to which ATSi Apply can send an HTTP POST request in order to get job details.

Job Details endpoint definition

URL Endpoint URL
Method POST
Query parameters No parameters
Consumes (Accept) application/json; charset=utf-8
Produces (Content-Type) application/json; charset=utf-8
Request payload (body) See below

Job Details request payload structure

Field Mandatory Type Description
Header Yes Header Job application’s metadata

Header

Field Mandatory Type Description
Id Yes String Conversation ID as UUID (correlation ID which helps to bind together all exchange messages between a job board, ATSi Apply and ATS)
JobBoardId Yes String Unique job board identifier
JobBoardName No String Human readable job board name
OriginalUrl Yes String Original apply URL published on the job board
EffectiveUrl Yes String Apply URL resolved from OriginalUrl (if OriginalUrl points to a final apply page, both URL fields contain the same value)

Response Payload

Expected HTTP status should be always set to 200 for both success and error responses. Information about the actual request status should be returned as a field in an HTTP response body.

Job Details response payload structure

Field Mandatory Type Description
Header Yes Header Response metadata
Body Yes Body Job details

Header

Field Mandatory Type Description
Id Yes String Conversation ID as UUID (correlation ID which helps to bind together all exchange messages between ATSi Apply and ATS)
Status Yes String If success then “OK”, otherwise “ERROR”
ErrorMsg No String Error code from the list of predefined error codes (see below) – if getting job details fails for any reason
ErrorDesc No String Non-technical description of an error

ErrorMsg

Value Description
INVALID_REQUEST Request from ATSi is invalid
TECHNICAL_ERROR Any other problem that occurred during getting job details

Body

Field Mandatory Type Description
Questions Yes Array [Question] Array of questions.
If there are no screening questions for the given job, an empty collection should be returned
JobStatus No String ACTIVE or EXPIRED

Question

Field Mandatory Type Description
Id Yes String Unique identifier of the question (in the scope of a job offer)
Label Yes String Content of the question
Repeatable Yes Boolean If set to true, then multiple answers to the question are possible
Fields Yes Array [QuestionField] Non-empty array of QuestionField

QuestionField

Field Mandatory Type Description
Id Yes String Unique identifier in the scope of the question
Label Yes (only for complex questions, i.e. having more than one QuestionField) String Content of the question answer
Type Yes String Type of the input field:

  • INPUT_TEXT
  • INPUT_INT
  • SINGLE_SELECT
  • MULTI_SELECT
  • DATE
  • RADIO
  • CHECKBOX
  • TEXTAREA
  • INFORMATION
Required Yes Boolean Specifies if an answer is mandatory for the given field
Values Yes Array [FieldValue] List of possible answers. It’s used for the following question types: SINGLE_SELECT, MULTI_SELECT, RADIO, CHECKBOX. If empty, then the jobseeker should provide an answer as a free text

FieldValue

Field Mandatory Type Description
Id Yes String Option identifier (unique within the question answer) for closed questions
Label Yes String Option label to be displayed

Question types supported by job boards

The following question types are currently supported by job boards: INPUT_TEXT, SINGLE_SELECT, RADIO, CHECKBOX, TEXTAREA.

Job board ID Job board name Supports SQ
careerstructure CareerStructure Yes
caterer Caterer Yes
catererglobal CatererGlobal Yes
cwjobs CW Jobs Yes
milkround Milkround Yes
retailchoice RetailChoice Yes
totaljobs Totaljobs Yes
irish_jobs_ie IrishJobs.ie No
jobs_ie Jobs.ie No
ni_jobs_com NIJobs.com No
StepStone_AT StepStone AT No
StepStone_BE StepStone BE No
StepStone_DE StepStone DE No
StepStone_FR StepStone FR No
StepStone_NL StepStone NL No
StepStone_PL StepStone PL No

Apply Service

Apply Service is expected to accept application data of an applicant, incl. CV and answers to screening questions. If the application process cannot be successfully completed using data sent in the apply request, ATS should return BackUrl that points to the prepopulated application form and use a “magic pixel” to inform ATSi about the application process status – see Application Tracking.

The endpoint URL must be sent to the ATSi Apply team in advance so it can be configured.

Endpoint requirements

  • use HTTPS protocol to ensure safe transfer of jobseekers’ personal data
  • be accessible from the Internet
  • only accept requests from ATSi Apply live servers (IPs will be provided during the implementation process)
  • The ATS should define a single endpoint where ATSi Apply will post application data to

Apply endpoint definition

URL Endpoint URL configured for the ATS in ATSi Apply configuration
Method POST
Query parameters No Parameters
Consumes (Accept) application/json; charset=utf-8
Produces (Content-Type) application/json; charset=utf-8
Request payload (body) See below

All data are sent as a body of a HTTP request. ATS should ignore any HTTP header or any field not listed in the following specification so that it can use a varied set of data submitted.

Expected HTTP status should be always set to 200 for both success and error responses. The actual application status should be returned as a field in an HTTP response body.

Apply request payload structure

Field Mandatory Type Description
Header Yes Header Job application metadata
Body Yes Body Jobseeker’s application data

Header

Field Mandatory Type Description
Id Yes String Conversation ID as UUID (correlation ID which helps to bind together all exchange messages between a job board, ATSi Apply and ATS)
 JobBoardId Yes String Unique job board identifier
JobBoardName No String Full, user friendly name of a job board, e.g. “Caterer”
OriginalUrl Yes String Apply URL as fed to the job board
EffectiveUrl Yes String Apply URL resolved from OriginalUrl (if OriginalUrl points to a final apply page, both URL fields contain the same value)
AtsiApplicationId No String Unique application id generated by ATSi

Body

Field Mandatory Type Description
Email Yes String Jobseeker’s email address
CV Yes TextDocument Jobseeker’s CV details
Answers Yes Array [Answer] Array of Answers. A jobseeker’s answers to the screening questions. Might be empty if a jobseeker has not answered to any question
BirthDate No String Birth date in ISO 8601 date format: YYYY-MM-DD
Gender No String Possible values: MALE / FEMALE
PrimaryLanguage No String Jobseeker’s primary language
Nationality No String Jobseeker’s nationality
FirstName No String Jobseeker’s first name
Surname No String Jobseeker’s last name
JobTitle No String Current / most recent job title
SalaryType No String Current / most recent salary type. Possible values: Annual, Daily, Hourly, None. If the value is set to None then SalaryRangeMin, SalaryRangeMax and SalaryCurrency should be ignored
SalaryRangeMin No String Current / most recent salary range lower boundary (numeric)
SalaryRangeMax No String Current / most recent salary range upper boundary (numeric)
SalaryCurrency No String Current / most recent salary currency in ISO 4217 format
WorkEligibility No String Jobseeker’s work eligibility. Possible values: UK, EU, NONE
CoverLetter No TextDocument Jobseeker’s cover letter
MessageToRecruiter No String Up to 4000 characters
AdditionalDocuments No Array [AdditionalDocument] Up to 7 encoded files
Mobile No String Jobseeker’s mobile phone number. Format: 00 + country code + (0) + phone number
Telephone No String Jobseeker’s phone number. Format: 00 + country code + (0) + phone number
Address No Address Jobseeker’s full address.
EmploymentHistory No Object CurrentEmployer (name of the current employer) + list of Items which represents employers. Each item may contain PositionHistory which is a list of positions took for a specific employer
Education No Object HighestDegree (name and field of study) + list of Items which represent Schools / Certificates
Qualifications No Array [Object] List of qualifications divided into 4 groups (Computer Skills, Natural Languages, PersonalSkills, Other Skills)

Address

Field Mandatory Type Description
StreetName No String Street name
BuildingNumber No String Building number
Unit No String Unit
PostalCode No String Postal code
City No String City name
CountryCode No String 2 digit ISO country code

TextDocument

Field Mandatory Type Description
FileType Yes String File type from list: txt, doc, docx, rtf, pdf, odt (case sensitive)
BinaryData Yes String Base64 encoded content of a CV file. Cannot be empty
FileName No String CV file name

AdditionalDocument

Field Mandatory Type Description
FileType Yes String File type from list: txt, doc, docx, rtf, pdf, odt, jpg, jpeg, png (case sensitive)
BinaryData Yes String Base64 encoded content of CV file. Cannot be empty
FileName No String CV file name

Answer

Field Mandatory Type Description
QuestionId Yes String Question identifier
AnswerRecords Yes Array [AnswerRecord] Non-empty array of answer records

AnswerRecord

Field Mandatory Type Description
AnswerFields Yes AnswerFieldMap Answer values to field mapping

AnswerFieldMap

Field Mandatory Type Description
$Key e.g. “lang” Yes String QuestionField identifier. It is required so that it would be possible to match an answer field with a question field. This is crucial for complex questions where more than one field is needed to provide an answer (e.g. information about language and skill level)
$Value e.g. “French” Yes Array [String] Non-empty list of answer values

Apply response payload structure

Field Mandatory Type Description
Header Yes Header Job application status
Body Yes Body Action to be performed after application

Header

Field Mandatory Type Description
Id Yes String Conversation ID as UUID (correlation ID which helps to bind together all exchange messages between ATSi Apply and ATS)
Status Yes String If success then “OK”, otherwise “ERROR”
ErrorMsg No String [ErrorMsg] Error code from the list of predefined error codes (see below) – if application fails for any reason
ErrorDesc No String Non-technical description of an error

ErrorMsg

Value Description
NOT_INTEGRATED_CUSTOMER Customer that ATS endpoint URL refers to is not integrated via API
JOB_NOT_AVAILABLE Job is no longer available or expired
DUPLICATED_REQUEST Same request sent more than once
INVALID_REQUEST Request from ATSi Apply is invalid
UNANSWERED_QUESTIONS Missing screening questions answers or incorrect answers
TECHNICAL_ERROR Any other problem that occurred during an application process

Body

Field Mandatory Type Description
BackUrl No URL Should be blank when application process is finished.BackUrl must be present only if a job seeker must be redirected to ATS page. This scenerio may happen if:
– application was succeful but more more job seeker’s data are expected. In such case BackUrl should be unique per each application and track down to application form prepopulated with jobseeker’s data.
– application was unsucceful because of any technical error or missing answers to screening questions
Redirect Yes String Possible values are YES | NO. Should be set to ‘YES’ if BackUrl is not null. Otherwise should be set to ‘NO’

Application Tracking

If the apply process cannot be succefully completed using the data sent to the ATS by ATSi, a BackUrl is expected in the response that points to the prepopulated ATS application form. ATS is expected to inform ATSi about the final application status using a “magic pixel” as follows:

  • If the application process has been successfully completed, the jobseeker should be presented with the confirmation page containing the following javascript code:
    <script language="javascript">
    (new Image()).src='https://www.at-ats.com/tracker/status?atsId={ATS_ID}&status=COMPLETE';
    </script>
    
  • If the application process cannot be completed, because the offer is no longer valid, the jobseeker should be presented with the page containing the following javascript code:
    <script language="javascript">
    (new Image()).src='https://www.at-ats.com/tracker/status?atsId={ATS_ID}&status=JOB_EXPIRED';
    </script>
    

{ATS_ID} value will be provided by the ATSi Apply team.