Users (v4)

The Users API lets you create and manage employee accounts in Ditio — the typical backbone of an HR-system sync. Each user needs at minimum a name, phone number, date of birth, employee number, and employment start date.

Base URL: api/v4/integration/users · Scope: ditioapiv3

Note

For new integrations, prefer the Employees API v5 — it has cleaner semantics, true PATCH support, and dedicated employment endpoints. The v4 Users API remains available but will not receive new features. For provisioning users from Microsoft Entra ID, see SCIM Provisioning instead.

# Test (default for all examples)
export DITIO_API_BASE="https://core-api.ditio.dev/core"
# Production: export DITIO_API_BASE="https://core-api.ditio.app/core"

Create a user

POST /api/v4/integration/users

curl -X POST "$DITIO_API_BASE/api/v4/integration/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "YOUR_COMPANY_ID",
    "employeeNumber": "1042",
    "firstName": "Kari",
    "lastName": "Nordmann",
    "mobileWork": "+4798765432",
    "birthDate": "1990-05-15",
    "employmentStartDate": "2026-03-01",
    "email": "kari.nordmann@example.com",
    "department": "Anlegg",
    "workTitle": "Maskinfører"
  }'

Response: the created user, including identityId and companyProfileId.

{
  "identityId": "auth0|abc123def456",
  "companyProfileId": "67a1b2c3d4e5f6a7b8c9d0e3",
  "companyId": "YOUR_COMPANY_ID",
  "employeeNumber": "1042",
  "firstName": "Kari",
  "lastName": "Nordmann",
  "mobileWork": "+4798765432"
}

Note

Save the identityId and companyProfileId — you need them for updates and lookups. PUT and DELETE address the user by identityId; PATCH and enable/disable use companyProfileId.

Required fields

Field	Type	Format	Description
companyId	string		Your Ditio company ID
employeeNumber	string		Unique employee number within the company
firstName	string		First name
lastName	string		Last name
mobileWork	string	+4798765432	Work phone number (used for SMS login)
birthDate	string	dd.MM.yyyy or yyyy-MM-dd	Date of birth
employmentStartDate	string	dd.MM.yyyy or yyyy-MM-dd	Employment start date

Optional fields

Field	Type	Description
email	string	Email address
mobilePrivate	string	Private phone number
workTitle	string	Job title
department	string	Department name
employmentEndDate	string	Employment end date (to terminate employment forward in time)
mainProjectNumber	string	Default project number for this employee
carRegNumber	string	Company car registration number
address	string	Home address
closestRelative	string	Emergency contact information
personalInfo	string	Additional personal information
cardId	string	Builder card / access card ID
cardExpirationDate	string	Card expiration date
payroll	bool	true = hourly wage, false = fixed salary
isDisabled	bool	Disable the user account (default: false)
defaultResourceNumber	string	Default resource/machine number
worktimeArrangementName	string	Work time arrangement name
organizationNumber	string	Organization number (for sub-contractor companies)
tags	array	List of user tags (see below)

User tags

Tags are key-value pairs attached to a user:

{
  "tags": [
    { "key": "safety-course", "value": "true" },
    { "key": "crane-license", "value": "A" }
  ]
}

Get users

All users in your company

GET /api/v4/integration/users

Optional query parameters:

Parameter	Type	Description
changedSince	datetime	Only return users modified after this date (note: slower query)
companyId	string	Filter to a specific company (useful if you have subsidiaries)
employmentLookbackDays	int	Only return users with active or recently ended employments (within X days)

# All users changed in the last 7 days
curl "$DITIO_API_BASE/api/v4/integration/users?changedSince=2026-06-27T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

# Only active employees (employment still active or ended within 30 days)
curl "$DITIO_API_BASE/api/v4/integration/users?employmentLookbackDays=30" \
  -H "Authorization: Bearer $TOKEN"

By company profile ID

GET /api/v4/integration/users/by-profile-id/{profileId}

By employee number

GET /api/v4/integration/users/by-employee-number/{employeeNumber}

Update a user (full)

PUT /api/v4/integration/users/{identityId}

Replaces all fields. Send the complete user object including identityId, companyProfileId, and all required fields.

curl -X PUT "$DITIO_API_BASE/api/v4/integration/users/auth0%7Cabc123def456" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identityId": "auth0|abc123def456",
    "companyProfileId": "67a1b2c3d4e5f6a7b8c9d0e3",
    "companyId": "YOUR_COMPANY_ID",
    "employeeNumber": "1042",
    "firstName": "Kari",
    "lastName": "Nordmann",
    "mobileWork": "+4798765432",
    "birthDate": "1990-05-15",
    "employmentStartDate": "2026-03-01",
    "workTitle": "Anleggsleder"
  }'

Note

The identityId in the URL must be URL-encoded (auth0|abc becomes auth0%7Cabc).

Update a user (partial)

PATCH /api/v4/integration/users/{companyProfileId}

Updates only the fields you include. Note that PATCH uses companyProfileId in the URL, not identityId.

curl -X PATCH "$DITIO_API_BASE/api/v4/integration/users/67a1b2c3d4e5f6a7b8c9d0e3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "workTitle": "Prosjektleder", "department": "Administrasjon" }'

Disable / enable a user

Instead of deleting a user, disable and re-enable them:

# Disable
curl -X PATCH "$DITIO_API_BASE/api/v4/integration/users/disable/67a1b2c3d4e5f6a7b8c9d0e3" \
  -H "Authorization: Bearer $TOKEN"

# Enable
curl -X PATCH "$DITIO_API_BASE/api/v4/integration/users/enable/67a1b2c3d4e5f6a7b8c9d0e3" \
  -H "Authorization: Bearer $TOKEN"

Both return 204 No Content on success.

Delete a user

DELETE /api/v4/integration/users/{identityId}

Caution

This permanently deletes the user and all related data. Prefer disabling. Check deletability first:

curl "$DITIO_API_BASE/api/v4/integration/users/is-identity-deletable/auth0%7Cabc123def456" \
  -H "Authorization: Bearer $TOKEN"
# Returns: true or false

Common integration patterns

Sync employees from an HR system

1. Initial load — create all employees with POST /api/v4/integration/users
2. Ongoing sync — periodically fetch GET /api/v4/integration/users?changedSince=LAST_SYNC_TIME and compare with your HR system
3. Updates — use PATCH to update changed fields
4. Offboarding — PATCH /disable/{companyProfileId} when an employee leaves (or set employmentEndDate)

Handling employee numbers

employeeNumber is the primary identifier for matching users between systems. It must be unique within a company. If your HR system doesn’t have employee numbers, generate sequential ones (e.g. 001, 002, …).

Related

• Employees API v5 — the modern replacement, recommended for new integrations
• SCIM Provisioning — directory-driven provisioning from Entra ID
• Certificates — attach qualifications to users by employee number
• Help centre: Brukerhåndtering — user administration in Ditio Web (Norwegian)