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

* Required for automatic user creation

Configuration Options

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:

1. Step 1: Create Talents and Skills First 
   Load all talents without any manager or mentor relationships. Focus on basic talent information, emails, and history.
2. Step 2: Verify All Talents Exist 
   Ensure all talents that will serve as managers or mentors are successfully created in the system.
3. 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:

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

1. External IDs: Always use consistent external identifiers to facilitate synchronization
2. Patch Mode: Prefer patch mode (usingPatch: true) to avoid losing unprovided data
3. Validation: Validate your data before sending to avoid bulk errors
4. History: Always include at least one history entry with since and workspaceId
5. Emails: To automatically create a user, always include an email marked as main: true
6. Test First: Always test with a small batch (5-10 talents) before running large imports
7. 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
  }
}