title: REST API Import category: HR Integration tags: hr, rest-api, integration, authentication, field-mapping priority: Normal

REST API Import

REST API Import connects IdentityCenter directly to your HR system's API, pulling employee data over HTTPS without the need for file exports or manual uploads. This approach provides fresher data, eliminates file-handling overhead, and supports near-real-time integration with modern HR platforms.

When to Use REST API Import

Setting Up a REST API Connection

Navigate to Administration > HR Import (/admin/hr-import) and select REST API as the source type.

Step 1: Endpoint Configuration

Step 2: Authentication

IdentityCenter supports three authentication methods for HR REST APIs:

API Key Authentication

The simplest authentication method. The API key is sent as a header or query parameter with each request.

Configuration example:

Header: X-API-Key: sk-hr-abc123def456

OAuth 2.0 Authentication

For HR systems that use OAuth 2.0 for API access. IdentityCenter supports the Client Credentials grant flow.

IdentityCenter automatically:

• Requests a new token before the first API call
• Caches the token for its validity period
• Refreshes the token when it expires
• Handles token refresh failures with retry logic

Basic Authentication

HTTP Basic Authentication with username and password.

Note: Basic Authentication sends credentials in every request (Base64-encoded, not encrypted). Always use HTTPS when using Basic Auth.

Step 3: Response Parsing

Configure how IdentityCenter extracts employee records from the API response.

JSON Path Configuration

Example API Response Structure

{
  "meta": {
    "total": 1250,
    "page": 1,
    "per_page": 100,
    "next_cursor": "eyJwYWdlIjoyf"
  },
  "data": {
    "employees": [
      {
        "id": "EMP001",
        "first_name": "John",
        "last_name": "Smith",
        "work_email": "john.smith@corp.com",
        "department": { "name": "Engineering", "code": "ENG" },
        "job_title": "Software Engineer",
        "manager": { "id": "EMP050" },
        "hire_date": "2024-06-15",
        "termination_date": null
      }
    ]
  }
}

For this response, the configuration would be:

Step 4: Field Mapping

Map JSON fields from the API response to IdentityCenter identity fields:

Nested field access: Use dot notation to access nested JSON properties. For example, department.name extracts "Engineering" from { "department": { "name": "Engineering" } }.

Array access: Use bracket notation for arrays. For example, phone_numbers[0].number extracts the first phone number.

Pagination Handling

Most HR APIs return results in pages. IdentityCenter supports three pagination methods:

Cursor-Based Pagination

The API returns a cursor token that identifies the next page of results.

Offset-Based Pagination

The API uses offset and limit parameters to paginate.

Page Number Pagination

The API uses a page number parameter.

Error Handling and Retry Logic

IdentityCenter implements robust error handling for API connections:

HTTP Status Code Handling

Retry Configuration

Testing the Connection

Before scheduling recurring imports, test the API connection:

1. Click Test Connection to verify connectivity and authentication
2. If successful, click Preview Data to see the first page of results
3. Verify that field mapping produces the expected values
4. Run a Test Import that processes all pages but does not commit changes
5. Review the test results for errors, warnings, and record counts

The test import report shows:

• Total API pages fetched
• Total records parsed
• Records matching existing identities
• New records (potential Joiners)
• Changed records (potential Movers)
• Terminated records (potential Leavers)
• Parsing errors with specific record details

Scheduling Recurring API Imports

Tip: If your HR API supports a modified_since or updated_after parameter, use delta imports to reduce data transfer and processing time. IdentityCenter automatically tracks the last successful import timestamp to pass as the delta parameter.

Common HR System API Patterns

Workday-Style APIs

Workday typically uses a SOAP or REST API with custom authentication and XML/JSON responses. Key considerations:

• Use the Workday REST API (available in recent versions) for easier integration
• Map Workday Worker data to IdentityCenter fields
• Handle Workday's custom date formats and organizational structures

BambooHR-Style APIs

BambooHR provides a straightforward REST API with API key authentication:

• Base URL: https://api.bamboohr.com/api/gateway.php/{subdomain}/v1
• Authentication: API key in header
• Employee endpoint: /employees/directory
• Supports field filtering to reduce payload size

ADP-Style APIs

ADP Workforce Now and similar platforms use OAuth 2.0 with certificate-based authentication:

• Requires SSL client certificate for mutual TLS
• Token endpoint uses client credentials grant
• Employee data is available through the Workers API
• Pay attention to ADP's rate limiting policies

Best Practices

1. Use OAuth 2.0 when available -- it provides the strongest security model for API authentication
2. Always use HTTPS -- never configure an HTTP endpoint for HR data
3. Set appropriate timeouts -- 30 seconds per request is a reasonable default
4. Monitor rate limits -- configure IdentityCenter to respect Retry-After headers
5. Test after HR system upgrades -- API response formats may change between versions
6. Store credentials securely -- never hardcode API keys or secrets; use IdentityCenter's encrypted credential store
7. Use delta imports when the API supports them to minimize data transfer
8. Log API responses at debug level during initial setup for troubleshooting, then reduce to error-only in production

Next Steps

• CSV Import -- Alternative file-based import method
• SCIM 2.0 Integration -- Standardized real-time provisioning
• HR Integration Overview -- Return to the HR integration overview
• Lifecycle Management Overview -- How imported data drives automation
• Getting Started -- Initial IdentityCenter setup