Custom Fields Schema

Overview

The ATS Anywhere API allows you to both create and update custom field schemas for the jobs listed on your site as well as return a list of all the fields you have created.

First let’s take a look at where you can find the additional custom fields you create, found under the default fields of a job listing (https://yourcompanyname.com//admin/jobs/edit/###):

In the above example we created 3 new custom fields cleverly titled  “My New Field #” which will be added for all of your job listings. Before using the API let’s take a look at the fields that you will be configuring for creating the field via the ATS Anywhere API:

Key Value Description
update_existing_data boolean Setting to true will update any previous custom field information
custom_fields_schema
field_name string Required field. The name in the system
field_type string, integer, decimal, boolean Required field. Defaults to “string” if not specified.
display_name string Required field. The form name that is displayed to the user.
default_value string Sets the text in the field.
required boolean Makes the question required when true and optional when false, with accompanying text in the field name.
whitelist_values array of strings Provides values for select list, and useful for setting up rules for validation.
blacklist_values array of strings Provides values for select list, and useful for setting up rules for validation.
ui_priority integer Determines the display order of the custom field in your job listing
ui_readonly boolean Makes the field unselectable when set to true
ui_input_type text_field, text_area,select The type of form input that will be used for the field
ui_hints string Provides the list of available items and order for a select dropdown field

Updating the Fields in Postman

Let’s go back to Postman and recreate the fields in our example above:

  • We’ll use the PUT method with the request URL:  https://YOURCOMPANY.applicant-tracking.com/api/v1/jobs/custom_fields_schema
  • Under Headers area put in the following column values:
    • Key: Content-type
    • Value: application/json
  • Under Body, select the “raw” and see if you can recreate the format as in the example
  • Hit “Send”

Here’s how it will look in Postman:

cURL Commands

curl -u YOUR_KEY https://YOURCOMPANY.applicant-tracking.com/api/v1/jobs/custom_fields_schema -H "Content-Type: application/json" \
  -d '{
	"update_existing_data": true,
	"custom_fields_schema": [
		{
		"field_name": "Custom Field 1",
		"field_type": "string",
    		"display_name": "My Custom Field 1",
    		"default_value": "This is your default value in a text field",
    		"required": true,
    		"whitelist_values": [],
    		"blacklist_values": [],
		"ui_priority": 0,
		"ui_readonly": true,
		"ui_input_type": "text_field",
		"ui_hints": []	    	
	    },
		{
		"field_name": "Custom Field 2",
		"field_type": "string",
    		"display_name": "My Custom Field 2",
    		"default_value": "This is your default value in a text area",
    		"required": true,
    		"whitelist_values": [],
    		"blacklist_values": [],
		"ui_priority": 2,
		"ui_readonly": false,
		"ui_input_type": "text_area",
		"ui_hints": []	    	
	    },	
	    {
		"field_name": "Custom Field 3",
		"field_type": "string",
    		"display_name": "My Custom Field 3",
    		"default_value": "This is your default value",
    		"required": true,
    		"whitelist_values": [],
    		"blacklist_values": [],
		"ui_priority": 1,
		"ui_readonly": false,
		"ui_input_type": "select",
		"ui_hints": "red"   	    	
	    }
    ]
}

And here is the corresponding payload:

{
    "company_id": "15664",
    "custom_fields_schema": [
        {
            "display_name": "My Custom Field 1",
            "field_type": "string",
            "default_value": "This is your default value in a text field",
            "required": true,
            "whitelist_values": [],
            "blacklist_values": [],
            "ui_priority": 0,
            "ui_readonly": true,
            "ui_input_type": "text_field",
            "ui_hints": [],
            "field_name": "Custom Field 1"
        },
        {
            "display_name": "My Custom Field 2",
            "field_type": "string",
            "default_value": "This is your default value in a text area",
            "required": true,
            "whitelist_values": [],
            "blacklist_values": [],
            "ui_priority": 2,
            "ui_readonly": false,
            "ui_input_type": "text_area",
            "ui_hints": [],
            "field_name": "Custom Field 2"
        },
        {
            "display_name": "My Custom Field 3",
            "field_type": "string",
            "default_value": "This is your default value",
            "required": true,
            "whitelist_values": [],
            "blacklist_values": [],
            "ui_priority": 1,
            "ui_readonly": false,
            "ui_input_type": "select",
            "ui_hints": [
                "red"
            ],
            "field_name": "Custom Field 3"
        }
    ],
    "created_at": "2018-03-22T20:33:47-07:00",
    "updated_at": "2018-04-01T18:39:12-07:00"
}

Note that a timestamp will be generated at the end.

And once again here’s how it will appear on your site:

Of course, you will likely have more creative field names than our example above (as well as more than one option in a select list) but this just shows what is possible from the the custom field endpoint.

Getting a List of Your Custom Fields

Once you have added a few fields retrieving a list of custom fields is simple.

  • Use the GET method with the request URL: https://YOURCOMPANY.applicant-tracking.com/api/v1/jobs/custom_fields_schema
  • Under Headers area put in the following column values:
    • Key: Content-type
    • Value: application/json
  • Hit Send, and within the Body frame you will see a full payload of the three jobs in our example: