Business rationale
At StepStone, we care not only about quantity but also about the quality of applicants delivered to our clients. We’d like to build our stronger partnerships with ATSes and Clients and receive feedback on Application Status and be able to provide this feedback to jobseekers using our services.
We’d like to:
- show job seekers information about their applications in one place for all jobs they applied to
- get some data proving the quality of applicants we send to clients and their ATSes in order to improve our services
Technical implementation
It is possible to share application statuses in form of .csv files. The files should be uploaded on daily basis to Stepstone cloud storage. Currently it is only possible to upload the files programmatically as there is no dedicated user interface to do it manually.
Please contact ATSi Quick Apply team and you will receive detailed instruction, a dedicated link and authorization token to start the integration work.
Using the credentials mentioned above, you will need to programmatically obtain a presigned URL for each file you wish to upload. The file should be not greater than 1 GB.
File content
File content depends whether your Applicant Tracking System is integrated with ATSi Quick Apply or not.
When Applicant Tracking System is integrated with ATSi Quick Apply
For clients who are already integrated with ATSi, the file should consist of the following columns:
| Field name | Is required? | Description | Notes |
|---|---|---|---|
| atsiApplicationId | yes | unique identifier of the application on ATSi Apply side | This identifier is included in the JSON body in the “Header” section in the field called “id”. It is not HTTP header. |
| rawStatus | yes | status of the application originating from the Applicant Tracking System | – |
| status | no | One of the normalized statuses used for analyzing the raw status data. It is up to customer to decide how raw status maps to normalized one. If the ‘status’ field is not submitted, we might ask you to provide the complete list of your raw statuses so that we can perform mapping on our end. | IN_REVIEW, CONTACT, INTERVIEW, OFFER, HIRED or REJECTED (check ATSi Status Mapping for details) |
| businessDate | yes | The date and time of the application status change in your system. | acceptable format: 2022-07-29T10:26:11.106Z the separator between date and time must be capital T timezone information is required use Z for UTC timezone use +/-HH:MM if other than UTC please use 00:00:00 for time if you don’t have actual information |
Please stick to camel case notation when naming the columns in your file.
When Applicant Tracking System is not integrated with ATSi Quick Apply
For clients who are not integrated with ATSi, the file should consist of the following columns:
| Field name | Is required? | Description | Notes |
|---|---|---|---|
| rawStatus | yes | status of the application originating from the Applicant Tracking System | |
| status | no | One of the normalized statuses used for analyzing the raw status data. It is up to customer to decide how raw status maps to normalized one. If the ‘status’ field is not submitted, we might ask you to provide the complete list of your raw statuses so that we can perform mapping on our end. | IN_REVIEW, CONTACT, INTERVIEW, OFFER, HIRED or REJECTED (check ATSi Status Mapping for details) |
| businessDate | yes | The date and time of the application status change in your system. | acceptable format: 2022-07-29T10:26:11.106Z the separator between date and time must be capital T timezone information is required use Z for UTC timezone use +/-HH:MM if other than UTC please use 00:00:00 for time if you don’t have actual information |
| jobOfferUrl | yes | URL to job form (not job description page) to which candidate applied | Should be the link from the Applicant Tracking System, not a multiposter link, e.g. https://yourcareerpage.com/carrer/offers/1?utm_source=stepstone |
| jobId | yes | id of the job from the Applicant Tracking System | Usually the ID is also included in the job offer URL. |
| applicationSource | yes | source of the application | Name of the job board that the application originated from |
| applicationCreationDate | yes | date and time when the application was created in the Applicant Tracking System | Example 2022-06-21T16:14:59.999Z |
| emailHash | no | candidate’s email hashed with SHA3-256 | Example: for email testCandidate@mailinator.com value is b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc |
| phoneNumberHash | no | candidate’s phone number hashed with SHA3-256 | for phone number 321321321 value is fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e |
Please stick to camel case notation when naming the columns in your file.
Additional requirements
Please follow the additional requirements below:
- include only those applications that originated at one of Stepstone job boards (e.g. Stepstone.com, totaljobs.com, etc.)
- each record in the file should represent a unique application status change (rawStatus). Include all status changes that took place since last upload.
- all records in the file should be ordered in chronological order (oldest records first)
- each file should include only those application status changes that occurred since last upload
- do not resubmit the records that were sent in the previous uploads
ATSi Status Mapping
Available statuses:
IN_REVIEW – Candidate has successfully applied – Application is received by the ATS and is under review
CONTACT – Application has successfully passed the review and recruiter has scheduled for a call (contact) with the applicant (including phone screening)
INTERVIEW – Candidate has passed the initial screening and recruiter arranged for an interview, background check or competence test with the applicant.
OFFER – Recruiter created an offer for an applicant
HIRED – Candidate was hired
REJECTED – Candidate was rejected/has withdrawn interest
Examples
Integrated
Please find below an example of .csv file for integrated ATS:
atsiApplicationId,rawStatus,status,businessDate
7426fbeb-d417-4268-9887-b5c9c0ed2bec,new application,APPLICATION_CONFIRMED,2022-07-29T10:26:11.106Z
ab927094-7394-4e1d-bab0-4c8c6096c04f,new application,QUALIFIED,2022-07-29T12:26:11.106Z
7426fbeb-d417-4268-9887-b5c9c0ed2bec,interview,HIRED,2022-07-29T13:26:11.106Z
98be1f88-4ee0-4547-92f0-1e464ee6fc60,1st interview,REJECTED,2022-07-29T11:26:11.106Z
7426fbeb-d417-4268-9887-b5c9c0ed2bec,1st interview,INTERVIEW,2022-07-29T14:26:11.106Z
ab927094-7394-4e1d-bab0-4c8c6096c04f,hired,,2022-07-29T15:26:11.106Z
e41efa52-9124-4ba1-b4f5-2eb654bcf395,new application,,2022-07-29T10:26:11.106Z
In some cases, the application might be originating from Stepstone but atsiApplicationId is not available, e.g. candidate indicated Stepstone as the referer in your custom application form. You might then:
- (1) submit an application status for such application in the same file. Please extend the file content to include all the fields as for non-integrated clients but use hashed email or hashed phone as the replacement for atsiApplicationId.
- (2) send us such applications in a separate file according to the specification for the non-integrated ATSes (read more in next paragraph)
Please see example below for case no. 1:
atsiApplicationId,rawStatus,status,businessDate,jobId,applicationSource,emailHash,phoneNumberHash,jobOfferUrl,applicationCreationDate
// example of the record for application with missing atsiApplicationId
,new application,APPLICATION_CONFIRMED,2022-07-29T10:26:11.106Z,123,stepstone,b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc,fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e,https://yourdomain.com/carrer/offers/123?utm_source=stepstone,2022-07-28T10:26:11.106Z
// example of the record for application with atsiApplicationId available
e41efa52-9124-4ba1-b4f5-2eb654bcf395,new application,,2022-07-29T10:26:11.106Z,,,,,,
Non-integrated
Please find below and example of .csv file for non-integrated ATSes:
rawStatus,status,businessDate,jobId,applicationSource,emailHash,phoneNumberHash,jobOfferUrl,applicationCreationDate
new application,APPLICATION_CONFIRMED,2022-07-29T10:26:11.106Z,123,stepstone,b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc,fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e,https://yourdomain.com/carrer/offers/123?utm_source=stepstone,2022-07-28T10:26:11.106Z
new application,QUALIFIED,2022-07-29T12:26:11.106Z,123,stepstone,b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc,fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e,https://yourdomain.com/carrer/offers/123?utm_source=stepstone,2022-07-28T10:26:11.106Z
interview,HIRED,2022-07-29T13:26:11.106Z,123,stepstone,b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc,fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e,https://yourdomain.com/carrer/offers/123?utm_source=stepstone,2022-07-28T10:26:11.106Z
1st interview,REJECTED,2022-07-29T11:26:11.106Z,123,stepstone,b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc,fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e,https://yourdomain.com/carrer/offers/123?utm_source=stepstone,2022-07-28T10:26:11.106Z
1st interview,INTERVIEW,2022-07-29T14:26:11.106Z,123,stepstone,b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc,fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e,https://yourdomain.com/carrer/offers/123?utm_source=stepstone,2022-07-28T10:26:11.106Z
hired,,2022-07-29T15:26:11.106Z,123,stepstone,b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc,fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e,https://yourdomain.com/carrer/offers/123?utm_source=stepstone,2022-07-28T10:26:11.106Z
new application,,2022-07-29T10:26:11.106Z,123,stepstone,b9a07d909c2770f970d290d189f73c4d97256b8ce3f7279a6a52126ceec596cc,fa4b7f08546c528124f91112dd2ee699fb08879f85b1a00c1ab937644e8ed00e,https://yourdomain.com/carrer/offers/123?utm_source=stepstone,2022-07-28T10:26:11.106ZTest scenarios
Testing the integration will require generating a few applications and progressing those along the recruitment funnel. Please see example scenarios below:
File no. 1
On that day, two candidates applied and candidate 001 progressed to ‘Phone Screening’ stage.
| atsiApplicationId | rawStatus | status | businessDate |
|---|---|---|---|
| atsiApplicationId001 | Applied | IN_REVIEW | 2022-07-29T10:26:11.106Z |
| atsiApplicationId001 | Reviewing | IN_REVIEW | 2022-07-29T12:26:11.106Z |
| atsiApplicationId001 | Phone screening | CONTACT | 2022-07-29T14:26:11.106Z |
| atsiApplicationId002 | Applied | IN_REVIEW | 2022-07-29T10:30:11.106Z |
File no. 2
On that day candidate 001 has gone through the interview and a background check.
Candidate 002 has been rejected.
A new candidate 003 has applied.
| atsiApplicationId | rawStatus | status | businessDate |
|---|---|---|---|
| atsiApplicationId001 | Interview – hiring manager | INTERVIEW | 2022-07-30T09:00:00.000Z |
| atsiApplicationId001 | Background check | INTERVIEW | 2022-07-30T13:16:00.000Z |
| atsiApplicationId002 | Rejected – skills | REJECTED | 2022-07-30T15:20:00.000Z |
| atsiApplicationId003 | Applied | IN_REVIEW | 2022-07-30T10:30:11.106Z |
File no. 3
On that day candidate 001 has been offered a job and accepted it.
Candidate 003 has been rejected.
Candidate 004 has applied and has been rejected.
| atsiApplicationId | rawStatus | status | businessDate |
|---|---|---|---|
| atsiApplicationId001 | Offer made | OFFER | 2022-07-31T08:00:00.000Z |
| atsiApplicationId001 | Hired – perm | HIRED | 2022-07-31T14:16:00.000Z |
| atsiApplicationId003 | Rejected – not possible to contact | REJECTED | 2022-07-31T16:20:00.000Z |
| atsiApplicationId004 | Applied | IN_REVIEW | 2022-07-31T11:30:11.100Z |
| atsiApplicationId004 | Rejected – not possible to contact | REJECTED | 2022-07-31T18:30:11.100Z |
File no. 4
On that day, candidate 003 has called the recruiter back and has been considered for the job again.
No other progress has been made on that day.
| atsiApplicationId | rawStatus | status | businessDate |
|---|---|---|---|
| atsiApplicationId003 | Phone screening | CONTACT | 2022-08-01T08:00:00.000Z |