BambooHR Cross-Border Employee Transfers: Field Mapping Sequence

When transferring an employee between countries using the BambooHR integration with Deel Payroll, the employee's record in BambooHR must be updated to reflect the new country and associated payroll entity. This process requires updating specific fields in a precise sequence to ensure successful contract creation and prevent currency or entity mismatches.

This guide provides the exact field-by-field update sequence needed for cross-border transfers.

In this article

• Why field sequencing matters
• Cross-Border Transfer Field update sequence
• Field Order and Dependency Notes
• Common Scenarios and Examples
• Troubleshooting

Why field sequencing matters

The BambooHR-Deel integration depends on proper field dependencies:

• The Country field controls the entity assignment and currency designation
• The Pay Group field must match the destination country's payroll structure
• Organizational fields (Location, Division, Compensation) provide context for the transfer
• Updating fields out of sequence can result in currency mismatches (e.g., GBP vs EUR) or contract creation failures

Cross-Border Transfer Field update sequence

Step 2: Update Country Field 

After organizational details are updated, change the country designation:

1. Navigate to the employee's Country field in BambooHR
2. Change the Country field to the destination country (e.g., from United Kingdom to Netherlands)
3. Wait for the change to save successfully. This field is critical for entity and currency assignment
4. Verify in the UI that the country has changed before proceeding to the next step

Important

This field directly determines which Deel Payroll entity will be used and which currency will apply to the contract. Failing to update this field will result in currency mismatches or contract creation blockers.

 

Step 3: Update Pay Group 

Once the country field is confirmed, update the pay group assignment:

1. Navigate to the employee's Pay Group field in BambooHR
2. Move the employee to the correctly mapped Pay Group for the destination country
3. Each country has a dedicated Pay Group ID in BambooHR — do not reuse pay groups across countries
4. Example mapping:
   • UK Pay Group ID (e.g., "UK_GP_2026")
   • Netherlands Pay Group ID (e.g., "NL_GP_2026")
5. Confirm the pay group change has saved.

Important

This field must be updated even if other organizational fields have already been adjusted. The Pay Group must match the destination country's payroll structure.

 

Field Order and Dependency Notes

Important

The Country field and Pay Group field must both be updated; updating only one will result in partial or failed sync.

• Country field dependency: The Country field directly determines the entity and currency. It must be updated before or at the same time as the Pay Group.
• Pay Group field dependency: The Pay Group must match the country you've assigned. Mismatched country-pay group combinations will trigger sync failures.
• Consequences of incomplete updates: If Country is updated but Pay Group is not, the sync will fail with a currency/entity mismatch error.
• Consequences of incorrect sequencing: Updating Pay Group before Country can result in invalid country-pay group combinations in the sync payload.

Common Scenarios and Examples

Scenario: UK to Netherlands Transfer

Troubleshooting

Sync Error: "Currency/Entity Mismatch"

Cause: Country and Pay Group fields are not aligned, or one was updated but not the other.

Resolution:

1. Return to the employee record in BambooHR
2. Verify both Country and Pay Group match the destination configuration
3. If mismatch exists, update the misaligned field(s)
4. Trigger a manual sync in Deel to reprocess

Sync Error: "Pay Group Not Found for Country"

Cause: The Pay Group assigned does not exist for the selected Country.

Resolution:

1. Verify the destination country has Pay Groups configured in BambooHR (Settings → Employee Fields → Pay Groups)
2. Confirm the Pay Group ID you selected is mapped to the correct destination country
3. Update the employee's Pay Group to the correct country-specific Pay Group
4. Retry the sync

Contract Not Created in Deel After Transfer

Cause: Changes may not have fully synced, or validation failed on one of the fields.

Resolution:

1. In Deel, open View Source Data for the employee
2. Confirm Country and Pay Group fields are present and correct in the sync payload
3. Check the Payroll Logs in Deel for specific error messages
4. If fields are missing or incorrect, update them in BambooHR and trigger a manual sync