Your bulk import failures are stemming from three distinct validation layers that need to be addressed systematically:
1. Special Characters in Names (your primary encoding issue):
Workday’s Sales Management API accepts UTF-8 encoded JSON, but you must ensure proper escaping within the JSON structure itself. The key distinction: characters like apostrophes, accented letters (é, ñ, ü), and standard punctuation should be sent as literal UTF-8 characters in your JSON strings - no special encoding needed. However, the ampersand (&) in company names requires careful handling because it can interfere with XML processing in Workday’s backend.
For names containing ampersands, use standard JSON string escaping - the ampersand itself is fine, but ensure there are no trailing/leading spaces that might cause parsing issues. For example: "Müller & Sons" works, but "Müller & Sons " (with trailing space) may fail validation.
The real culprit in your scenario is likely mixed character encoding in your source data. Legacy CRM exports often contain Windows-1252 encoded characters that look correct but aren’t valid UTF-8. Run your input file through a UTF-8 validation tool and re-encode if necessary: `iconv -f WINDOWS-1252 -t UTF-8 input.json > output.json
2. Missing Required Fields (comprehensive field mapping):
The bulk import endpoint enforces a broader set of required fields than documented because it triggers the full customer creation business process. Based on wd-r2-2023 configuration, these fields are mandatory for Sales Management customer creation:
- Customer_Name (obvious)
- Customer_Reference_ID (your external ID)
- Customer_Category (typically ‘Business’ or ‘Individual’)
- Currency_Reference (must match tenant’s enabled currencies)
- Payment_Terms_Reference (default to ‘Net 30’ if unsure)
- Worktags (at least one, usually Customer_Group or Region)
- Bill_To_Contact and Bill_To_Address (even if same as primary)
The validation error ‘missing required fields’ is frustratingly vague because Workday doesn’t specify which fields in the API response. Use this API call to identify the complete field set:
GET /customers/{existing_customer_id}
Include all reference fields
Compare your payload structure against a successfully created customer - any field present in the GET response should be included in your bulk import.
3. Bulk Import Endpoint Behavior (batch processing requirements):
The bulk endpoint processes records sequentially and has a strict validation mode. Unlike single-record creation which can use default values, bulk imports require explicit values for all fields. Additionally, the endpoint has a 1000-record per batch limit and a 5MB payload size limit.
Structure your bulk payload with proper error isolation:
{
"customers": [
{
"Customer_Name": "O'Brien Industries",
"Customer_Reference_ID": "CRM-001",
"Customer_Category": {"ID": "Business"},
"Currency": {"ID": "USD"},
"Payment_Terms": {"ID": "NET_30"}
}
]
}
Recommended Solution Approach:
- Pre-process your 5,000 records: validate UTF-8 encoding, normalize special characters, remove trailing spaces
- Create a field mapping template based on a GET_Customers call for an existing record in your tenant
- Split your import into batches of 500 records (safer than the 1000 limit)
- Implement retry logic with detailed error logging for failed records
- For the 30% failing records, export them separately and validate each required field is populated with properly encoded values
The combination of character encoding issues and missing conditional required fields explains your 30% failure rate. Once you normalize the encoding and ensure all business-process-required fields are populated, your success rate should exceed 95%.