Context
Manatal allows dynamic application forms. Those are forms that can be defined for each jobs and are later displayed on the career page.
Each of the field in the form is linked to a candidate field. Enabling for better candidate information from the moment they apply on the career page.
We now offer this possibility for our API users.
Preliminary information
All application forms must be defined directly within Manatal.
The API allows you to retrieve the form and then submit the application using this form.
Using application form
Implementing dynamic application form on the career page is done in 2 steps.
- Getting the list of fields that compose the application form
- Submitting answers
1. Getting the list of fields
Doing a GET request on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/ will return a list of all application form fields.
Details on the fields can be found on the Application form page.
All the information needed to handle the field display and check is included in this endpoint.
Once the form is displayed, the user can enter the values. The next step is to submit those values.
2. Submitting the response
To submit the response to the form, a POST on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/ will create the applicant and associate it with the job.
Details on the submission can be found on the Application form page
The response is nested within the application_data object.
The subjects are formatted as follows: {"field_id": response_value}
- The
field_idis the id obtained at the previous call - The
response_valueis the value entered by the user. Note that theresponse_valuemust follow the type of the field.
Example
GET on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/
[
{
"id": 11,
"label": "Full Name",
"slug": "full_name",
"is_required": true,
"display_type": "text",
"type": "char",
"field_category": "candidate_field"
},
{
"id": 12,
"label": "Cover Letter",
"slug": "description",
"is_required": false,
"display_type": "long_text",
"type": "longtext",
"field_category": "candidate_field"
},
{
"id": 13,
"label": "Email",
"slug": "email",
"is_required": true,
"display_type": "text",
"type": "char",
"field_category": "candidate_field"
}
]
Here there are 2 required fields. So it is possible to submit the response as follows:
{
"application_data": {
"11": "John Doe",
"13": "[email protected]",
}
}
Display types
You may have noticed that we have a display_type. This is to allow the UI to display different type for form fields depending on what has been configured in Manatal.
You can find the types possible in /career-page/{client_slug}/jobs/{id}/application-form/
Example
{
"id": 14,
"label": "Preferred Working Hours",
"slug": "preferworkinghours",
"is_required": false,
"display_type": "multiple_select_dropdown",
"type": "array",
"choices": [
"8am-5pm",
"12pm-9pm",
"6pm-3am",
"12am-9pm",
"None of above"
],
"field_category": "candidate_field"
},
{
"id": 15,
"label": "Which countries can you relocate?",
"slug": "customcheckboxtestlongoptionscutoff",
"is_required": false,
"display_type": "checkbox",
"type": "array",
"choices": [
"Australia",
"New Zealnad",
"Germany",
"Other"
],
"field_category": "candidate_field"
},
{
"id": 16,
"label": "Blood Type",
"slug": "bloodtypes",
"is_required": false,
"display_type": "multiple_choice",
"type": "char",
"choices": [
"A",
"B",
"AB",
"B+",
"O",
"None",
"Other"
],
"field_category": "candidate_field"
},
{
"id": 17,
"label": "Favorite programming language",
"slug": "favoriteprogramminglanguage",
"is_required": false,
"display_type": "dropdown",
"type": "char",
"choices": [
"JavaScript",
"C#",
"C++",
"Python",
"Perl",
"Ruby",
"Java",
"None of above"
],
"field_category": "candidate_field"
}
{
"application_data": {
"14": ["8am-5pm", "12pm-9pm"],
"15": ["Germany"],
"16": "AB,O",
"77": "Python",
}
}
Field category
Candidate field
This is the most common field. This means that the field is linked to a field in the candidate summary.
To handle this field, the only thing required is to ensure that the response respect the type.
Nationalities and Languages
If the field has field_category = "candidate_field" and slug="nationalities or languages". Manatal is expecting nationalities ids instead of string.
In order to be able to submit the correct id and also display the list of possible nationalities, you need first to get the list of possible nationalities.
This can be done on the following endpoints.
Example
GET on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/
{
"id": 20,
"label": "Spoken Language",
"slug": "languages",
"is_required": true,
"display_type": "",
"type": "char",
"field_category": "candidate_field"
},
{
"id": 21,
"label": "Nationalities",
"slug": "nationalities",
"is_required": true,
"display_type": "",
"type": "char",
"field_category": "candidate_field"
},
It is needed to submit the response as follows:
{
"application_data": {
"20": "40,55",
"21": "77,15",
}
}
Experience
An experience field is a more complex data structure. It requires more information than a simple input.
The values needed can be found in the Application form page.
When receiving such a field, the UI needs to adapt to allow the candidate to enter the required values.
Once the candidate has filled all the information, it is possible to pass the data to the submission.
The experiences are all defined within a list under the field id.
Example
GET on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/
[
{
"id": 11,
"label": "Full Name",
"slug": "full_name",
"is_required": true,
"display_type": "text",
"type": "char",
"field_category": "candidate_field"
},
{
"id": 12,
"label": "Cover Letter",
"slug": "description",
"is_required": false,
"display_type": "long_text",
"type": "longtext",
"field_category": "candidate_field"
},
{
"id": 13,
"label": "Experience",
"slug": "experience",
"is_required": true,
"display_type": "",
"type": "",
"field_category": "experiences"
}
]
It is needed to submit the response as follows:
{
"application_data": {
"11": "John Doe",
"13": [
{
"title": "Senior Developer",
"employer": "Manatal China",
"salary": "11111",
"currency_code": "USD",
"frequency": "year",
"started_at": "2021-06-02",
"ended_at": "2021-06-22",
"start_at": "2021-06-02",
"end_at": "2021-06-22",
"is_current_employer": false,
"location": "Beijing",
"description": "I am building the future of applications"
},
{
"title": "Junior Developer",
"employer": "Manatal Thailand",
"salary": "2222",
"currency_code": "USD",
"frequency": "year",
"started_at": "2021-06-02",
"ended_at": "2021-06-22",
"start_at": "2021-06-02",
"end_at": "2021-06-22",
"is_current_employer": false,
"location": "Beijing",
"description": "I am helping build the best ATS"
},
]
}
}
Educations
An education field is a more complex data structure. It requires more information than a simple input.
The values needed can be found in the Application form page.
When receiving such a field, the UI needs to adapt to allow the candidate to enter the required values.
Once the candidate has filled all the information, it is possible to pass the data to the submission.
The educations are all defined within a list under the field id.
Example
GET on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/
[
{
"id": 11,
"label": "Full Name",
"slug": "full_name",
"is_required": true,
"display_type": "text",
"type": "char",
"field_category": "candidate_field"
},
{
"id": 12,
"label": "Birthdate",
"slug": "birth_date",
"is_required": false,
"display_type": "date",
"type": "datetime",
"field_category": "candidate_field"
},
{
"id": 13,
"label": "Educations",
"slug": "",
"is_required": true,
"display_type": "",
"type": "char",
"field_category": "educations"
}
]
It is needed to submit the response as follows:
{
"application_data": {
"11": "John Doe",
"12": "1994-03-17",
"13": [
{
"school": "INSA Lyon",
"degree_name": "Master's Degree",
"specialization": "TC",
"started_at": "2021-06-02",
"ended_at": "2021-06-09",
"start_at": "2021-06-02",
"end_at": "2021-06-09",
"final_grade": "33",
"score_type": "010",
"location": "Los Angeles",
"description": "This is a good school"
},
{
"school": "La Prats",
"degree_name": "High School diploma",
"specialization": "PT",
"started_at": "2021-05-29",
"ended_at": "2021-06-16",
"start_at": "2021-05-29",
"end_at": "2021-06-16",
"final_grade": "1",
"score_type": "1",
"location": "Cluny",
"description": "This is it"
}
],
}
}
Social media
An social media field is not more complicated that a field which is validated for a url.
In that case, make sure that the entry is a url using a URL validator.
Example
GET on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/
[
{
"id": 11,
"label": "Full Name",
"slug": "full_name",
"is_required": true,
"display_type": "text",
"type": "char",
"field_category": "candidate_field"
},
{
"id": 12,
"label": "Birthdate",
"slug": "birth_date",
"is_required": false,
"display_type": "date",
"type": "datetime",
"field_category": "candidate_field"
},
{
"id": 13,
"label": "LinkedIn Profile",
"slug": "",
"is_required": false,
"display_type": "",
"type": "char",
"field_category": "social_media"
},
]
It is needed to submit the response as follows:
{
"application_data": {
"11": "John Doe",
"12": "1994-03-17",
"13": "https://linkedin.com/johndoe"
}
}
Resume and attachments
Passing a url
A resume is a link to a file which will be downloaded.
Please refer to the Uploading a file documentation for more information.
Example
GET on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/
[
{
"id": 11,
"label": "Full Name",
"slug": "full_name",
"is_required": true,
"display_type": "text",
"type": "char",
"field_category": "candidate_field"
},
{
"id": 12,
"label": "Resunme",
"slug": "Resume",
"is_required": false,
"display_type": "",
"type": "char",
"field_category": "resume"
},
{
"id": 13,
"label": "LinkedIn Profile",
"slug": "",
"is_required": false,
"display_type": "",
"type": "char",
"field_category": "social_media"
},
]
It is needed to submit the response as follows:
{
"application_data": {
"11": "John Doe",
"12": "https://manatal.s3.southeast-ap-1.amazonaws.com/resume/resume.pdf",
"13": "https://linkedin.com/johndoe"
}
}
Passing a base64 file - for resume only
It is possible to upload a resume file by passing a base64 string in place of the file url.
The file will be decoded in Manatal then uploaded in our systems.
The restrictions which apply on the file url are the same as the base64 file.
Please refer to the Uploading a file documentation for more information.
There is a possibility that the file takes too long to upload and the request will timeout.
In that case the candidate will be created without resume.
We are continuously working on improving the experience to ensure that the upload is a secure and reliable as possible.
Example
GET on https://api.manatal.com/open/v3/career-page/client_slug/jobs/id/application-form/
[
{
"id": 11,
"label": "Full Name",
"slug": "full_name",
"is_required": true,
"display_type": "text",
"type": "char",
"field_category": "candidate_field"
},
{
"id": 12,
"label": "Resume",
"slug": "Resume",
"is_required": false,
"display_type": "",
"type": "char",
"field_category": "resume"
},
{
"id": 13,
"label": "LinkedIn Profile",
"slug": "",
"is_required": false,
"display_type": "",
"type": "char",
"field_category": "social_media"
},
]
It is needed to submit the response as follows:
{
"application_data": {
"11": "John Doe",
"12": "WW91ckJhc2U2NEZpbGVIZXJl",
"13": "https://linkedin.com/johndoe"
}
}
Other
This field category is handled much like the candidate field. The only thing to ensure is to respect the type.
Fields marked as other will not appear in the main candidate page
The difference with candidate field is that the response will not be mapped to a candidate field.
It will not appear in the candidate summary page in Manatal.
Salary currency
Manatal allows to define the expected and current salaries for candidates through the following fields current_salary and expected_salary which are defined in the application forms.
[{
"id": 21115,
"label": "Current salary",
"is_required": false,
"is_protected": false,
"client_field": 39,
"client_field_slug": "current_salary",
"client_field_field_type": "",
"client_field_answer_choices": [],
"client_field_answer_choice_type": "text",
"social_media": null,
"response_type": "integer",
"field_type": "candidate_field",
"horizontal_rank": null,
"vertical_rank": 9
},
{
"id": 21116,
"label": "Expect salary",
"is_required": false,
"is_protected": false,
"client_field": 50,
"client_field_slug": "expected_salary",
"client_field_field_type": "",
"client_field_answer_choices": [],
"client_field_answer_choice_type": "text",
"social_media": null,
"response_type": "integer",
"field_type": "candidate_field",
"horizontal_rank": null,
"vertical_rank": 10
}]
It is possible to also pass the currency to make sure that the currency fits your application needs.
To do so, the application needs to retrieve Manatal currencies and pass the corresponding id when posting the application form.
Example with above fields:
GET on https://api.manatal.com/open/v3/currencies/
[
{
"id": 82,
"name": "Moroccan Dirham",
"symbol": "MAD",
"code": "MAD",
"logo": "https://manatal-backend-staging-public-assets.s3.amazonaws.com/media/currency_logo/currency_mad_logo_RfvmRKP.png"
},
{
"id": 61,
"name": "Bolivian Boliviano",
"symbol": "Bs",
"code": "BOB",
"logo": "https://manatal-backend-staging-public-assets.s3.amazonaws.com/media/currency_logo/currency_bob_logo_WKq6jA3.png"
},
{
"id": 10,
"name": "Pakistani Rupee",
"symbol": "PKRs",
"code": "PKR",
"logo": "https://manatal-backend-staging-public-assets.s3.amazonaws.com/media/currency_logo/currency_pkr_logo_NrvbN9o.png"
}
]
It is needed to submit the response as follows to have the salaries expected as Boliviano (BOB) and the current salary as Moroccan Dirham (MAD)
{
"application_data": {
"21115": "424",
"21116": "233",
"current_currency": 82,
"expected_currency": 61,
},
}