​
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 Mappings

​
Step 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 both Connector 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 parameter include_custom_fields=true to your requests:

if you are trying to get Custom Fields for employees model your request will look like this:

GET https://api.bindbee.dev/api/hris/v1/employees?include_custom_fields=true

Example response with custom fields:

{
  "id": "emp_123",
  "name": "John Doe",
  "custom_fields": {
    "cost_center_name": "Engineering-NA",
    "hourly_rate": 45.0
  }
}

​
Best Practices

  1. Naming Conventions

    • Use clear, descriptive names
    • Follow snake_case formatting
    • Avoid generic names like “custom1”, “custom2”

  2. JSON Path(JMESPath) Expressions

    • Test expressions thoroughly before saving
    • Consider data type consistency

  3. 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

For more details on How to write custom JMESPath Expression visit JMESPath Documentation