[ReadMe] Getting started with the Workelo API 💻 – Workelo - Help Center

Technical documentation

https://api.workelo.eu/docs/apis

Getting started

💡 The Workelo API lets you integrate the platform’s features directly into your systems and applications. This documentation gradually guides you through using the API to automate your HR processes and manage your employee journeys.

📋 Overview

The Workelo API (version 1.6) is a REST API that enables you to automate and integrate your HR processes.

What can you do?

✅ Manage journeys for collaborators (onboarding, crossboarding, offboarding)
✅ Manage employees and their fields
✅ Collect administrative data
✅ Manage organizations and levels
✅ Automate HR actions

API architecture

Type: REST API
Format: JSON
Authentication: OAuth 2.0
Base URL: https://api.workelo.eu/v1/
Rate limit: 1000 requests per hour per token

🔑 Key concepts

Before you start, here are the essential notions defined in Workelo

👥 Employees and collaborators

Employee: A person who is part of the database in Workelo.

Collaborator: An employee experiencing a key moment (journey) with Workelo.

Flexible identification in the API:

ID (default identifier)
external_id: your system identifier
Email: email address

🛤️ Journeys (Tracks)

Journey: The key moment experienced by the collaborator within the company.

Types of key moments:

Onboarding: Process of integrating a new collaborator into the company
Crossboarding: Process of supporting internal mobility or a role change
Offboarding: Process of supporting a collaborator leaving the company

Statuses:

Draft draft
Invitation sent invitation_sent
Scheduled scheduled
In progress in_progress
Closed closed
Cancelled cancelled

Involved roles: An employee involved in a collaborator’s key moment

HR rh
Administrative owner second_rh
Manager manager
Buddy buddy
Contributor second_manager

📝 Resources

Resource: A specific element configured to enrich the experience offered on Workelo

Available resource types:

Form: Resource aimed at collecting administrative information from the employee
Document: File or resource to view, download, or sign within a journey
Survey : Resource aimed at collecting feedback from the collaborator
Quiz: Resource aimed at testing the collaborator’s knowledge
Task: Concrete action to be completed by a role or by the collaborator within a journey
Kit: Resource aimed at defining an accessory, tool, software, or access that must be prepared or retrieved for the collaborator
Content: Resource aimed at pushing information to the collaborator via a file or a link
Communication: Message or notification sent to users within a journey

🏢 Organizational structure

Environment: The level of the organizational directory chosen to define the different scopes of the account.

In the API:

Level Organizations: hierarchical levels (Division, Department)
Unit Organizations: concrete units (HR, IT, Marketing)

🎯 Templates

Template: A set of resources scheduled relative to a key date, each with a designated owner

🛠️ Best practices

HTTP response codes

200: Success
201: Resource created
404: Resource not found
422: Unprocessable data
401: Unauthorized

Error handling

Example 422 error:

{
"errors": ["Invalid email format", "Unit organization not found"],
"message": "unprocessable_entity",
"code": 422
}

Limits and performance

Rate limit: 1000 requests per hour per token
Pagination: Use limit and offset for large lists
Timeout: Minimum 30 seconds recommended
Retry: Exponential backoff for 5xx errors

Recommended steps

🔑 Test authentication with your credentials
👥 Create a test employee to get familiar
🛤️ Launch a simple journey using the default templates
📝 Explore forms and their data structure
🔄 Implement synchronization with your existing system
⚙️ Automate your processes according to your use cases

🎯 Tip: Start small! A basic onboarding journey using existing templates helps you master the concepts before implementing advanced logic.

Go further

🚀 First steps

Step 1: Get your API credentials

You can create your credentials in your Workelo account under Account > Advanced > API.

client_id
client_secret

Step 2: First call — List employees

# 1. Get an access token
curl -X POST https://api.workelo.eu/v1/tokens
-F "client_id=your_client_id" \\
-F "client_secret=your_client_secret"

# 2. Use the token to list employees
curl -X GET https://api.workelo.eu/v1/employees
-H "Authorization: Bearer YOUR_TOKEN"

Step 3: Understand a typical response

{
  "data": [
    {
      "id": 123,
      "first_name": "Marie",
      "last_name": "Dubois",
      "email": "marie.dubois@entreprise.com",
      "role": "colleague",
      "unit_organization": {
        "id": 5,
        "name": "Service RH"
      }
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 10,
    "offset": 0
  }
}

💡 First success! If you get this response, your integration works. You can now explore the other endpoints.

🔐 Authentication

The API uses OAuth 2.0 with short‑lived access tokens.

Get a token

POST /tokens
Content-Type: multipart/form-data

client_id=your_client_id
client_secret=your_client_secret

Response:

{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"token_type": "Bearer",
"expires_in": 3600
}

Use the token

Add the token to the header of all your requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

⏰ Lifetime: Tokens are valid for 1 hour and can be reused. Plan for automatic renewal.

👥 Employee management

List employees

GET /employees

or 

GET /employees?limit=10&offset=0&role=colleague

Filtering parameters:

role: colleague, manager, hr, owner
unit_organization_ids: organization IDs (comma‑separated)

Create an employee

POST /employees
Content-Type: application/json

{
  "first_name": "Marie",
  "last_name": "Dubois",
  "email": "marie.dubois@entreprise.com",
  "job_position": "Manager",
  "external_id": "EMP-001",
  "unit_organization_id": 5,
  "user_role_id": 234
}

Add custom identifications

POST /employees/{employee_id}/identifications
Content-Type: application/json

{
  "identification_resource_id": 5,
  "value": "BADGE-001"
}

Search an employee by external_id

GET /employees?external_id=EMP-001

🛤️ Collaborator journeys

Create a journey

POST /tracks
Content-Type: application/json


{
  "mobility": "onboarding",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "employee": {
    "external_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "job_position": "string",
    "unit_organization_id": 0
  },
  "implications": {
    "hr_id": 0,
    "second_hr_id": 0,
    "manager_id": 0,
    "second_manager_id": 0,
    "buddy_id": 0
  },
  "template_ids": [
    0
  ]
}

Send the journey invitation

PUT /tracks/{id}/start
Content-Type: application/json

{
"invite_at": "2025-10-01"
}

Generate a secure access link

GET /user_magic_links/{employee_id}

Response:

{
"magic_link": "https://app.workelo.eu/magic/97abc...",
"expires_in": 7200
}

Security: Magic links expire after 2 hours and are only accessible to collaborators with an active journey.

📝 Forms and information

List a journey’s forms

GET /tracks/{id}/forms

Statuses:

opened: form opened, awaiting input
closed: form closed and completed
missing_validation: awaiting HR validation

View details and submitted data

GET /forms/{id}

Response structure:

{
  "id": 123,
  "name": "Informations personnelles", 
  "status": "closed",
  "paperworks": [
    {
      "id": 456,
      "paperwork_resource_name": "Adresse personnelle",
      "value": "123 Rue de la Paix, Paris",
      "paperwork_files": []
    },
    {
      "id": 789, 
      "paperwork_resource_name": "Photo d'identité",
      "value": null,
      "paperwork_files": [
        {
          "id": 101,
          "file": {"url": "https://..."}
        }
      ]
    }
  ]
}

Update a piece of information

PUT /paperworks/{id}
Content-Type: application/json

{
"value": "New value"
}

Manage uploaded files

Retrieve a file:

GET /paperwork_files/{id}

Upload a new file:

POST /paperwork_files/
Content-Type: multipart/form-data

paperwork_id={paperwork_id}
file={file_data}

📄 Documents

List a journey’s documents

GET /tracks/{id}/documents

Document statuses:

supplying: being prepared by the organization
receipting: available for collaborator action
finalized: action completed by the collaborator

Download the file attached to a document

GET /attachments/{id}

Response (base64‑encoded file):

{
"id": 123,
"name": "Employment contract",
"filename": "contrat_martin_jean.pdf",
"extension": "pdf",
"content": "JVBERi0xLjQKMSAwIG9iao8CAovVHlwZSA..."
}

🏢 Organizational structure

Understand the hierarchy

List organization levels:

GET /level_organizations

List units within a level:

GET /unit_organizations?level_organization_id={level_id}

Create an organization

POST /unit_organizations
Content-Type: application/json

{
"external_id": "IT-001",
"name": "IT Department",
"level_organization_id": 2,
"parent_id": 15,
"language": "fr"
}

Manage an employee’s scopes

Grant access to a unit:

POST /employees/{id}/unit_organization_managements
Content-Type: application/json

{
"unit_organization_id": 42
}

Revoke access:

DELETE /unit_organization_managements/{management_id}

⚙️ Advanced features

Templates and models

List available templates:

GET /templates

or

GET /templates?mobility=onboarding&unit_organization_id=42

Use templates at creation time:

Templates are specified via template_ids when creating a journey.

⚡ Performance: Applying templates can take time. The journey is created immediately, resources are added in the background.

Tracking and logs

GET /logs?event=track_creation&from=2025-09-01T00:00:00Z&to=2025-09-09T23:59:59Z

Main events:

user_creation: employee creation
track_creation: journey creation
track_start: journey start
form_completion: form completed

Related to

Technical documentation

Getting started

📋 Overview

What can you do?

API architecture

🔑 Key concepts

👥 Employees and collaborators

🛤️ Journeys (Tracks)

📝 Resources

🏢 Organizational structure

🎯 Templates

🛠️ Best practices

HTTP response codes

Error handling

Limits and performance

Recommended steps

Go further

🚀 First steps

Step 1: Get your API credentials

Step 2: First call — List employees

Step 3: Understand a typical response

🔐 Authentication

Get a token

Use the token

👥 Employee management

List employees

Create an employee

Add custom identifications

Search an employee by external_id

🛤️ Collaborator journeys

Create a journey

Send the journey invitation

Generate a secure access link

📝 Forms and information

List a journey’s forms

View details and submitted data

Update a piece of information

Manage uploaded files

📄 Documents

List a journey’s documents

Download the file attached to a document

🏢 Organizational structure

Understand the hierarchy

Create an organization

Manage an employee’s scopes

⚙️ Advanced features

Templates and models

Tracking and logs

Related articles