HR System Integration Guide

Complete workflows for syncing employee data between your HR system and Beeline. This guide covers the four essential HR operations with real-world examples.

🚀 Quick Start

Base URL: https://qaserv.beeline.life/api/v1

Authentication: Authorization: Api-Key YOUR_API_KEY

External ID Format: system_name:external_id (e.g., payspace:EMP123)

ℹ️All operations are organization-scoped. Your API key automatically determines which organization's data you can access.

👋

New Hire Onboarding

Automatically create new users in Beeline when employees join your organization.

Trigger: New Employee Record Created

Detect when a new employee is added to your HR system (e.g., Payspace, Workday, BambooHR).

ℹ️Common triggers: 'When a record is created', 'New row in database', 'Webhook received'

Create User in Beeline

Send employee data to Beeline to create their learning account.

POST/api/v1/pre-create-users/

{
  "identifier": "payspace:EMP12345",
  "email": "john.doe@company.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+27812345678",
  "job_role_id": "550e8400-e29b-41d4-a716-446655440000",
  "group_ids": [
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

ℹ️identifier format: 'system_name:external_id' (must be unique per organization)

ℹ️phone_number should include country code (e.g., +27 for South Africa)

ℹ️job_role_id is optional but recommended for competency tracking

ℹ️group_ids are optional - omit to add user to root organization group

Handle Response

Process the API response to confirm user creation or handle existing users.

{
  "status": "created",
  "user_id": 12345,
  "organization_membership_id": 67890,
  "message": "User created successfully"
}

ℹ️status 201: New user created

ℹ️status 200: Existing user added to your organization

ℹ️Store user_id and organization_membership_id for future operations

🔄

Update Employee Details

Sync changes from your HR system to Beeline (name changes, role updates, group assignments).

Check if User Exists (Recommended)

First verify the user exists to avoid handling 404 errors in your automation.

GET/api/v1/check-by-identifier/?identifier=payspace:EMP12345

{
  "status": "ACTIVE",
  "user_id": 12345,
  "organization_membership_id": 67890,
  "role": "USER"
}

ℹ️status can be: NOT_FOUND, ACTIVE, or REVOKED

ℹ️If NOT_FOUND, use the New Hire workflow instead

ℹ️If REVOKED, consider using the Restore workflow

Update User Information

Send updated employee data to Beeline. Only include fields that changed.

PATCH/api/v1/modify-by-identifier/

{
  "identifier": "payspace:EMP12345",
  "first_name": "Jonathan",
  "job_role_id": "770e8400-e29b-41d4-a716-446655440002",
  "group_ids": [
    "660e8400-e29b-41d4-a716-446655440001",
    "660e8400-e29b-41d4-a716-446655440003"
  ]
}

ℹ️All fields are optional - only send what changed

ℹ️job_role_id update will set new role as PRIMARY and mark old roles as INACTIVE

ℹ️group_ids fully replaces user's group memberships (include all groups they should belong to)

Verify Update Success

Confirm the update was processed successfully.

{
  "status": "success",
  "message": "User updated successfully",
  "user_id": 12345
}

ℹ️status 200: Update successful

ℹ️status 404: User not found (identifier may be incorrect)

🚫

Revoke User Access

Suspend user access when employees leave or go on extended leave. This is a soft delete - user data is preserved.

Trigger: Employee Status Changed

Detect when an employee's status changes to 'Terminated', 'Resigned', or 'On Leave' in your HR system.

ℹ️Revocation is reversible - use this instead of deletion

ℹ️User retains all learning history and progress data

Revoke User in Beeline

Suspend the user's access while preserving their data.

POST/api/v1/revoke-by-identifier/

{
  "identifier": "payspace:EMP12345"
}

ℹ️User can no longer log in

ℹ️All learning progress and history is preserved

ℹ️Can be reversed with the Restore workflow

Confirm Revocation

Verify the user's access has been revoked.

{
  "status": "success",
  "message": "User revoked successfully",
  "user_id": 12345
}

ℹ️status 200: User revoked successfully

ℹ️status 404: User not found or already revoked

↩️

Restore User Access

Reactivate previously revoked users when employees return from leave or are rehired.

Trigger: Employee Reactivation

Detect when a previously terminated or on-leave employee is reactivated in your HR system.

ℹ️Restores access to all previous learning progress

ℹ️Use this for returning employees or corrections

Restore User in Beeline

Reactivate the user's account with all their historical data intact.

POST/api/v1/restore-by-identifier/

{
  "identifier": "payspace:EMP12345"
}

ℹ️All learning progress is immediately accessible

ℹ️User can log in with their previous credentials

ℹ️Competency scores and certifications are restored

Optionally Update Details

If the employee's details changed (new role, different groups), update them after restoration.

PATCH/api/v1/modify-by-identifier/

{
  "identifier": "payspace:EMP12345",
  "job_role_id": "880e8400-e29b-41d4-a716-446655440005",
  "group_ids": [
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

ℹ️This step is optional - only needed if employee details changed

ℹ️Common for rehired employees in different roles

Integration Patterns

✅

Check-Then-Act Pattern

Recommended approach to avoid error handling complexity

Always check if a user exists before performing operations:

1. GET /check-by-identifier/?identifier=payspace:EMP123
2. Based on status:
   - NOT_FOUND → Create user (POST /pre-create-users/)
   - ACTIVE → Update user (PATCH /modify-by-identifier/)
   - REVOKED → Restore user (POST /restore-by-identifier/)

Benefits: Simpler logic, fewer error cases, better automation reliability

⚠️

Error-Based Pattern

Alternative approach using HTTP status codes

Handle different scenarios based on API responses:

Try operation → Handle response:
- 200/201 → Success
- 404 → User doesn't exist, create them
- 409 → Conflict (e.g., external ID already exists in another org)

Note: More complex error handling, but fewer API calls

📦

Batch Processing

Efficiently sync large employee datasets

For bulk operations (e.g., initial setup or nightly sync):

Process users in batches of 50-100
Add delays between batches to respect rate limits
Log all operations for audit trail
Implement retry logic for failed requests
Use the check endpoint first to categorize operations

⚡

Real-Time Sync

Immediate updates via webhooks or triggers

For event-driven integrations:

Subscribe to HR system webhooks (employee.created, employee.updated, etc.)
Process events individually as they occur
Implement idempotency to handle duplicate events
Use exponential backoff for retries

Power Automate Setup

Step-by-step configuration for Microsoft Power Automate integration with your HR system.

New Hire Flow

Automatically create Beeline accounts when new employees are added

⚡

Trigger

New employee in your HR database/system

When a record is created

Create user in Beeline

HTTP - POST

URI:https://qaserv.beeline.life/api/v1/pre-create-users/

Method:POST

Headers:Authorization: Api-Key YOUR_API_KEY

Body:Dynamic content from trigger

Check if creation succeeded

Condition

Condition:Status code equals 201 or 200

Notify HR team of new user creation

Send email

💡Store your API key in Power Automate's secure variable storage

💡Map HR system fields to Beeline fields in the HTTP action body

💡Add error handling to retry failed requests

Update Employee Flow

Sync employee changes to Beeline automatically

⚡

Trigger

Employee record updated in HR system

When a record is modified

Check if user exists in Beeline

HTTP - GET

URI:https://qaserv.beeline.life/api/v1/check-by-identifier/?identifier=@{concat('payspace:', triggerBody()?['EmployeeID'])}

Method:GET

If user exists and is active

Condition

Condition:status equals 'ACTIVE'

Update user details

HTTP - PATCH

URI:https://qaserv.beeline.life/api/v1/modify-by-identifier/

Method:PATCH

Body:Only changed fields

💡Only send fields that actually changed to minimize API calls

💡Use Power Automate's 'Filter array' action to detect changes

Troubleshooting

Common issues and their solutions when integrating HR systems with Beeline.

Problem	Cause	Solution
User not found `404`	The identifier doesn't exist in your organization, or the format is incorrect	Verify identifier format (system:external_id). Check if user was created in correct organization. Use /check-by-identifier/ to confirm status.
External ID already exists `409`	Another user in your organization already has this external identifier	External IDs are unique per organization. If you're trying to update a user, use /modify-by-identifier/ instead of /pre-create-users/.
Invalid job role `400`	The job_role_id doesn't exist or doesn't belong to your organization	Use GET /api/v1/job-roles/ to retrieve valid job role IDs for your organization. Verify the UUID format is correct.
Invalid group `400`	One or more group_ids don't exist or don't belong to your organization	Use GET /api/v1/groups/ to retrieve valid group IDs. Remove any groups that don't exist. Verify UUID format.
Phone number format error `400`	Phone number is missing country code or has invalid format	Include country code (e.g., +27 for South Africa). Format: +[country code][number]. Remove spaces and special characters except '+'.
User can't see content `N/A`	User not assigned to correct groups or lacks permissions	Verify user's group_ids match where content is published. Check that user's role has appropriate permissions. Review organization's content visibility settings.
Duplicate users created `N/A`	Automation ran multiple times or different identifiers used for same person	Implement idempotency checks. Use /check-by-identifier/ before creating. Ensure consistent identifier format across all automations.
Updates not reflecting `200`	Caching in your integration or wrong endpoint used	Verify you're using PATCH /modify-by-identifier/ not POST. Check that identifier matches exactly. Allow 1-2 seconds for propagation.

Best Practices

🔒Security

Never hardcode API keys in automation flows
Use secure variable storage (Azure Key Vault, etc.)
Rotate API keys quarterly
Monitor API usage for anomalies
Use HTTPS for all API calls

📊Data Quality

Validate email formats before sending
Standardize phone number formats
Trim whitespace from all text fields
Use consistent identifier formats
Handle special characters in names properly

🔄Reliability

Implement retry logic with exponential backoff
Log all API calls for audit trail
Set up monitoring and alerts
Handle rate limits gracefully
Test failure scenarios regularly

⚡Performance

Batch operations when possible
Only send changed fields in updates
Use check endpoint to avoid unnecessary calls
Cache job role and group IDs locally
Schedule bulk syncs during off-peak hours

Need Help?

Our team is here to help you successfully integrate your HR system with Beeline.

💼

Enterprise Support

Dedicated support for complex integrations, custom workflows, and enterprise deployments.

Contact Enterprise Support →

📚

API Reference

Complete endpoint documentation with examples, parameters, and response formats.

View API Documentation →