API Payload Validation & Format Guide

This document outlines the validation rules, required formats, and data types for each field in the employee integration API payload. Adhering to these specifications ensures seamless automated updates and synchronization with your QuestionPro Employee Experience roster.

When constructing your JSON payload, please ensure each field strictly follows the guidelines below:

• uniqueIdentifier

Requirement: Required if Employee ID is enabled for the folder; optional/ignored if disabled.

Format: Alphanumeric. The only allowed special character is a hyphen (-).

Example: "WFTest-2026121" or "2026-HBRPOIG8F"

• emailAddress

Requirement: Must be a valid email format. Required if Employee ID for the folder is disabled.

Example: "[email protected]"

• firstname & lastname

Requirement: Optional (can be left empty or omitted).

Format: Any standard text value.

Example: "firstname": "John", "lastname": "Doe"

• mobileNumber

Requirement: Optional (can be left empty).

Format: {country-code}-{phone} (Format must be explicitly matching +CC-XXXXXX). The number of digits supported in the mobile number depends on the specified country code.

Example: "+91-1234567890"

• supervisorUniquField

Requirement: Optional (can be left empty).

Format: Dependent on folder configurations:
- If Employee ID is disabled: Must be a valid email address.
- If Employee ID is enabled: Must be a valid Employee ID.

Example (Email): "[email protected]"

Example (Employee ID): "WFTest-20267856"

• startDate

Requirement: Optional (can be left empty).

Format: MM/DD/YYYY

Example: "10/23/2011"

• endDate

Requirement: Optional (can be left empty).

Format: MM/DD/YYYY

Behavior: Providing a valid value in this field automatically updates the employee's lifecycle status to "Terminated".

Example: "11/27/2015"

• status

Requirement: Optional.

Format: Allowed values are strictly limited to "Active" or "Terminated".

Behavior: If left empty or omitted, the system will default the employee's status to "Active".

Example: "Terminated"

• customFields

The customFields array contain objects with two parameters: type and value.

1. type (Custom Field Title)

Critical Requirement: Strict Exact Match. The type must match the system's custom field title character-for-character. Do not append formatting hints, brackets, or explanatory notes to the title. If there is a mismatch, the system will fail to recognize the field and the payload data will not be saved.

• Valid: "Date of Birth" (Matches the system title exactly)
• Invalid: "Date of Birth (MM/DD/YYYY)" (Adding formatting notes breaks the system database lookup)

2. value (Field Data)

Requirement: Cannot be empty if the custom field object is sent. The format depends entirely on the pre-configured custom field type:

• Single Select / Dropdown: Must exactly match one of the pre-configured valid choices in the portal.
• Date Type: Must strictly follow the MM/DD/YYYY format.
• Text Input Type: Accepts any standard text value string.

Below is a standard production-ready JSON payload template implementing all correct rules, date constraints, and custom field strict exact matches:

{
    "uniqueIdentifier": "2026-HBRPOIG8F",
    "emailAddress": "[email protected]",
    "firstname": "Danielle",
    "lastname": "Johnson",
    "mobileNumber": "+91-1234567890",
    "supervisorUniquField": "2026-HBRPOTYJKL",
    "startDate": "01/21/2009",
    "endDate": "11/28/2015",
    "status": "Terminated",
    "customFields": [
        {
            "type": "Location",
            "value": "INDIA"
        },
        {
            "type": "Date of Birth",
            "value": "03/21/1998"
        },
        {
            "type": "Reason for change",
            "value": "Career Growth"
        }
    ]
}