Overview
Custom Fields can be configured at two levels:- Connector Level: Applied to a specific connector instance
- Organization Level: Applied to all connectors of a specific integration type
When the same custom field name exists at both levels, the connector-level
field takes precedence.
Creating a Custom field
Creating a Custom field involves two main steps: Step 1: Create New Field Step 2: Configure Field MappingsStep 1: Create New Field
- Click the “New Field” button in the top right corner
- Fill out the necessary details in the dialog.
- Click “Create”
Name of custom field must be unique and naming should follow
snake_case
Step 2: Configure Field Mappings
After creating the field, you’ll be redirected to the mapping configuration screen where you can set up bothConnector Level
and Organization Level
mappings.
Connector Level Mapping
- Click on “Connector Level”
- Select your connector from the Dropdown
- Fill or Select Data field box, you can choose either
- Select Mapping from Options
- Click the
</>
button to view the raw JSON response and click the desired field - Enter the JSON Path(JMESPath) expression directly
If your JSON Path (JMESPath) expression is incorrect, then while requesting
the
custom_fields
via APIs, you will not receive an error. Instead, the API
will respond with "INVALID_JSON_PATH"
mapped to the incorrectly configured
field. Ensure that all JMESPath expressions are valid to retrieve the intended
data correctly.Organization Level Mapping
- Click on “Organization Level”
- Select your integration from the Dropdown
- Fill or Select Data field box, you can choose either
- Select Mapping from Options
- Click the
</>
button to view the raw JSON response and click the desired field - Enter the JSON Path(JMESPath) expression directly.
You can add multiple mappings to a single custom field by clicking the “Add
New” button and repeating the process for different connectors or
integrations.
Using Custom Fields
To include custom fields in your API responses, add the query parameterinclude_custom_fields=true
to your requests:
if you are trying to get Custom Fields for employees
model your request will look like this:
Best Practices
-
Naming Conventions
- Use clear, descriptive names
- Follow snake_case formatting
- Avoid generic names like “custom1”, “custom2”
-
JSON Path(JMESPath) Expressions
- Test expressions thoroughly before saving
- Consider data type consistency
-
Organization vs Connector Level Mapping
- Use Organization Level fields for data that’s consistent across all connectors
- Use Connector Level fields for connector-specific data
- Review existing Organization Level fields before creating Connector Level duplicates