API: Our ready-to-use recipes 👩‍🍳 – Workelo - Help Center

Here is a complete guide, structured by main user story, with all the required API calls in order (including prerequisite calls to retrieve IDs).

🙋 To get started with the API, please refer to the dedicated documentation first.

1. Manage your employee directory 👥

Retrieve the required IDs

→ Retrieve the user_role_id corresponding to the desired role (colleague, manager, hr...) :

GET /user_roles

→ Retrieve the id of the organization to assign the employee to:

GET /unit_organizations

→ Retrieve the identification_resource_id of available custom fields (badge, employee ID, etc.):

GET /identification_resources

Create the employee

POST /employees

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

Add custom identification fields

POST /employees/{employee_id}/identifications

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

View / Update the employee

GET  /employees/{id}
PUT  /employees/{id}
GET  /employees?role=manager          ← list by role
GET  /employees?external_id=EMP-001  ← find by external ID

2. Manage your organisational structure 🏢

Understand the existing hierarchy

→ List the levels (e.g. Division, Department, Site):

GET /level_organizations

→ List the units of a given level:

GET /unit_organizations?level_organization_id={level_id}

Create a new organization

POST /unit_organizations

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

Manage an employee's scopes (access scope)

GET    /employees/{employee_id}/unit_organization_managements
POST   /employees/{employee_id}/unit_organization_managements
       { "unit_organization_id": 42 }
DELETE /unit_organization_managements/{management_id}

3. Create a journey 🛤️

Prerequisites — retrieve the required IDs

→ unit_organization_id of the employee's organization:

GET /unit_organizations

→ id of the manager, HR, buddy, etc.:

GET /employees?role=manager
GET /employees?role=hr

→ id of the templates to apply:

GET /templates?mobility=onboarding&unit_organization_id={id}

Create the journey (draft status)

POST /tracks

{
  "mobility": "onboarding",
  "start_date": "2026-06-01",
  "end_date": "2026-09-01",
  "employee": {
    "first_name": "John",
    "last_name": "Martin",
    "email": "john.martin@company.com",
    "job_position": "Developer",
    "unit_organization_id": 5
  },
  "implications": {
    "hr_id": 101,
    "manager_id": 202,
    "buddy_id": 303
  },
  "template_ids": [999056]
}

Launch the journey and send invitations

PUT /tracks/{id}/start

{
  "invite_at": "2026-05-28"   ← optional: employee invitation date
}

4. Monitor and track journeys 🧐

List and filter journeys

GET /tracks
GET /tracks?status=in_progress
GET /tracks?status=draft

Available statuses: draft, invitation_sent, scheduled, in_progress, closed, cancelled

View journey details (with live metrics)

→ Returns journey health, progression, action availability rate, number of completed actions:

GET /tracks/{id}

Update a journey (dates, stakeholders)

PUT /tracks/{id}

{
  "start_date": "2026-06-15",
  "apply_on_actions": true,     ← automatically shifts actions
  "implications": {
    "manager_id": 205
  }
}

5. Manage administrative tasks 📃

List the forms of a journey

GET /tracks/{track_id}/forms
GET /tracks/{track_id}/forms?status=opened              ← awaiting completion
GET /tracks/{track_id}/forms?status=missing_validation  ← awaiting HR validation

View details and entered data

→ Returns all paperworks with their filled-in values:

GET /forms/{id}

Update a field value

PUT /paperworks/{id}

{ "value": "New value" }

Manage files uploaded in a form

GET  /paperwork_files/{id}       ← retrieve a file
POST /paperwork_files            ← upload a file
     { "paperwork_id": 456, "file": "..." }

List available form resources

GET /paperwork_resources
GET /paperwork_resources?type=selection   ← dropdown lists
GET /paperwork_resources?type=date

List the documents of a journey

GET /tracks/{track_id}/documents

Statuses: supplying (being prepared), receipting (available), finalized (completed)

Download a file (base64)

GET /attachments/{id}

List available document resources

GET /document_resources
GET /document_resources?type=sign
GET /document_resources?type=download

6. Manage dropdown option lists 🔽

List the options of a resource

GET /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}

Use limit / offset pagination for large lists.

Create a simple option

POST /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}

{
  "value": "Permanent contract",
  "external_id": "contract_permanent",
  "position": 1
}

Create an option with a parent (dependent list)

POST /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}

{
  "value": "Paris 1st",
  "external_id": "75056",
  "position": 1,
  "parent_id": 1001
}

The parent_id is the id of the parent collection_value (e.g. the postal code 75001).

Update an option (label, position, or parent)

PUT /collection_values/{id}

{
  "value": "Paris 1st Arrondissement",   // update the label
  "position": 2,                          // change the order
  "parent_id": 1050                       // move to a different branch
}

Existing values in journeys retain their previous value (no cascade update).

7. Generate a secure access link (Magic Link) 🔗

GET /user_magic_links/{employee_id}
GET /user_magic_links_by_email/{email}
GET /user_magic_links_by_external_id/{external_id}

⏱️ Links expire after 2 hours and only work if the employee has an active journey.

8. Analyse and audit activity 📈

GET /logs
GET /logs?event=user_creation&from=2026-01-01&to=2026-05-26
GET /logs/{uuid}

9. View assigned actions (stakeholders) ✔️

→ Retrieve the stakeholder's id:

GET /employees?role=manager

List a stakeholder's actions

GET /owners/{owner_id}/actions
GET /owners/{owner_id}/actions?limit=20&offset=0

📊 Visual summary

User Story	Main calls
Create an employee	`GET /user_roles` → `GET /unit_organizations` → `POST /employees`
Enrich a profile	`GET /identification_resources` → `POST /employees/{id}/identifications`
Manage organizations	`GET /level_organizations` → `POST /unit_organizations`
Create a journey	`GET /unit_organizations` + `GET /employees` + `GET /templates` → `POST /tracks`
Send the invitation	`PUT /tracks/{id}/start`
Track journeys	`GET /tracks` → `GET /tracks/{id}`
Update a journey	`PUT /tracks/{id}`
Administrative forms	`GET /tracks/{id}/forms` → `GET /forms/{id}` → `PUT /paperworks/{id}`
Documents	`GET /tracks/{id}/documents` → `GET /attachments/{id}`
Magic Link	`GET /user_magic_links/{id}`
Stakeholder actions	`GET /employees` → `GET /owners/{id}/actions`
Logs & audit	`GET /logs`

📑 Related articles

Related to