Required modules:
Use Whoz Talent Bulk Save API
Overview
The Bulk Save Talents API allows you to create or update multiple talents in a single request. This feature is particularly useful for bulk imports, synchronizations with other systems, or batch talent updates. The API can also automatically create users associated with talents when a primary email address is provided, and assign them basic access rights.
Important: Creation operations take longer than updates due to additional internal operations including access rights configuration and user account creation.
Endpoint
POST /api/talent/bulk/save
Prerequisites
- Existing Relationships: Any managers and mentors referenced must already exist.
Request Format
{
"data": [
{
"firstName": "John",
"lastName": "Doe",
"emails": [
{
"address": "john.doe@example.com",
"main": true
}
],
"history": [
{
"since": "2026-01-01",
"workspaceId": "5f7b1a5b9d3e6c001a7e1234",
"scope": "POOL",
"roleExternalId": "ROLE-001",
"gradeExternalId": "GRADE-001"
}
],
"staffable": true
}
],
"configuration": {
"usingPatch": true,
"trustedSource": false
}
}Automatic User Creation
When you include a primary email address in a talent, the API automatically creates:
- A talent with the provided information
- A user with the email address as username
- A link between the talent and the user
Important: The created user will have the MEMBER role at the federation level and the RESTRICTED role at the workspace level. No email invitation is sent automatically when creating users through the bulk API. To send an invitation, use the invitation API separately.
Note: If the main parameter is not explicitly provided in the email object, it will be considered as true by default.
Required Fields
| Field | Description | Required |
|---|---|---|
| firstName | Talent first name | Yes |
| lastName | Talent last name | Yes |
| emails | Email list with at least one primary email (main: true) | Yes* |
| history | History with since and workspaceId | Yes |
| externalId | External identifier to reference the talent | Recommended |
* Required for automatic user creation
Configuration Options
| Option | Default | Description |
|---|---|---|
| usingPatch | true | If true, only updates provided fields |
| trustedSource | false | If true, status will not be reset to DRAFT |
⚠️ Critical: Always Use Patch Mode
You should NEVER send requests with usingPatch: false. Always keep usingPatch: true to avoid unintentionally replacing entire talent records and losing data that was not included in your request.
Update Behavior
If a talent already exists (identified by internal or external ID):
- The API updates information according to the chosen mode (usingPatch)
- If the primary email address changes, the username is also updated
- Existing access rights are preserved
Updating Operational Situation
Since this API operates in PATCH mode, you can update the operational situation by sending a history entry with the same since date. This allows you to:
- Overwrite workspace operational situation (e.g., change from Workspace A to Workspace B)
- Update role or grade for an existing operational period
Benefit: You can load talents before workspaces are fully configured, then update workspace operational situation during rollout
Recommended Implementation Strategy
To avoid errors related to missing relationships (managers, mentors), follow this step-by-step approach:
- Step 1: Create Talents and Skills First
Load all talents without any manager or mentor relationships. Focus on basic talent information, emails, and history. - Step 2: Verify All Talents Exist
Ensure all talents that will serve as managers or mentors are successfully created in the system. - Step 3: Add Management Relationships
Use a second bulk update operation to add manager and mentor relationships now that all referenced talents exist in the federation.
This approach prevents errors from referencing managers or mentors that don't exist yet, ensuring a smooth bulk import process.
API Response
{
"errors": [
{
"code": "UNKNOWN_WORKSPACE",
"message": "Unknown Workspace 621bd81dcf36e1a258e5848c",
"locations": [
{
"index": 0,
"id": "603cb26702c5254bf093010f",
"externalId": "ABC00123"
}
]
}
],
"metadata": {
"count": 4,
"created": 2,
"updated": 1,
"took": 12
}
}Error Handling
- The API accumulates errors for each talent and continues processing others
- Errors are returned with indices of affected talents and specific error codes
- Processing continues even if some talents fail
- Each item in the batch is treated separately - the API will process all items it can handle even if others fail
Recommendations
- Recommended Maximum Batch Size: Limited to 300 talents per request
Relationships with Other Entities
The API allows defining relationships with other entities:
| Relationship | Field | Description |
|---|---|---|
| Manager | manager.externalId | Defines the talent's manager |
| Mentor | mentor.externalId | Defines the talent's mentor |
| Qualifications | qualifications[].externalId | Associates qualifications |
Important: When using external IDs to reference managers, mentors, or qualifications, Whoz will automatically resolve these to internal IDs. You do not need to know the internal Whoz IDs - simply provide the external IDs you've assigned to these entities.
Best Practices
- External IDs: Always use consistent external identifiers to facilitate synchronization
- Patch Mode: Prefer patch mode (usingPatch: true) to avoid losing unprovided data
- Validation: Validate your data before sending to avoid bulk errors
- History: Always include at least one history entry with since and workspaceId
- Emails: To automatically create a user, always include an email marked as main: true
- Test First: Always test with a small batch (5-10 talents) before running large imports
- Staged Approach: Follow the recommended implementation strategy - create talents first, then add relationships
Usage Examples
Simple Creation with User
{
"data": [{
"externalId": "EXT-001",
"firstName": "John",
"lastName": "Doe",
"emails": [{
"address": "john.doe@example.com",
"main": true
}],
"history": [{
"since": "2026-01-01",
"workspaceId": "5f7b1a5b9d3e6c001a7e1234",
"scope": "POOL",
"roleExternalId": "CONSULTANT",
"gradeExternalId": "SENIOR"
}],
"staffable": true
}],
"configuration": {
"usingPatch": true
}
}Update with External ID
{
"data": [{
"externalId": "EXT-001",
"firstName": "John",
"lastName": "Doe-Smith",
"tags": ["senior", "developer"]
}],
"configuration": {
"usingPatch": true
}
}Update Operational Situation (Workspace Change)
{
"data": [{
"externalId": "EXT-001",
"history": [{
"since": "2026-01-01",
"workspaceId": "5f7b1a5b9d3e6c001a7e5678",
"scope": "EMPLOYEE",
"roleExternalId": "SENIOR-CONSULTANT",
"gradeExternalId": "GRADE-3"
}]
}],
"configuration": {
"usingPatch": true
}
}Creation with Relationships
{
"data": [{
"externalId": "EXT-001",
"firstName": "John",
"lastName": "Doe",
"emails": [{
"address": "john.doe@example.com",
"main": true
}],
"history": [{
"since": "2026-01-01",
"workspaceId": "5f7b1a5b9d3e6c001a7e1234",
"scope": "EMPLOYEE"
}],
"manager": {
"externalId": "MGR-001"
},
"mentor": {
"externalId": "MNT-001"
},
"qualifications": [{
"externalId": "QUAL-001"
}],
"staffable": true
}],
"configuration": {
"usingPatch": true
}
}
Comments
0 comments
Article is closed for comments.