Looma API

GET /api/v1/analytics/headcount

Read current headcount by dimension

Scope analytics:read

Responses

200

Tenant-scoped headcount analytics; small groups are withheld.

curl "https://api.looma.hr/api/v1/analytics/headcount" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/analytics/headcount", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/analytics/headcount",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/analytics/headcount", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/analytics/headcount/trend

Read monthly headcount trend

Scope analytics:read

Responses

200

Tenant-scoped headcount analytics; small groups are withheld.

curl "https://api.looma.hr/api/v1/analytics/headcount/trend" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/analytics/headcount/trend", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/analytics/headcount/trend",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/analytics/headcount/trend", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/benefits

List benefit plans

Scope benefits:read

Query parameters

limit integer

cursor string

Responses

200

A tenant-scoped cursor page.

curl "https://api.looma.hr/api/v1/benefits?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/benefits?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/benefits?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/benefits?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/benefits/{benefit}/participants

List benefit participants

Scope benefits:read

Path parameters

benefit string required

Query parameters

limit integer

cursor string

Responses

200

A tenant-scoped cursor page.

curl "https://api.looma.hr/api/v1/benefits/ben-11/participants?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/benefits/ben-11/participants?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/benefits/ben-11/participants?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/benefits/ben-11/participants?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/people

List the employee directory

Current employees as of today, ordered by employee number then id. Uses the same effective-dated primary-employment semantics as the app, then applies the integration field-visibility resolver per person. Pass nextCursor back as cursor unchanged.

Scope people:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor from a previous response's nextCursor. Do not construct or parse it.

includeFormer boolean

Include people whose employment has ended.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields EmployeePage

hasMore boolean required

items array of Employee required

items[].accountId string

items[].businessTitle string

items[].countryCode string

items[].department string required

items[].employeeNumber string required

items[].employmentId string

items[].firstName string required

items[].hasPhoto boolean

items[].hiddenFields array of string

items[].id string required

items[].jobTitle string required

items[].lastName string required

items[].legalEntity string required

items[].lifecycle string

items[].location string required

items[].revision integer required

items[].startDate string (date) required

items[].status string required

items[].workEmail string required

items[].workFromHome boolean or null

items[].workerType string

nextCursor string

Responses

200

A cursor page of employees.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/people?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/people?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/people?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/people?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": true,
  "items": [
    {
      "countryCode": "SE",
      "department": "People",
      "employeeNumber": "E-1001",
      "firstName": "Alex",
      "id": "p-1001",
      "jobTitle": "People Partner",
      "lastName": "Nguyen",
      "legalEntity": "Northwind Sweden AB",
      "location": "Stockholm",
      "revision": 1,
      "startDate": "2024-03-01",
      "status": "active",
      "workEmail": "alex.nguyen@example.test",
      "workerType": "employee"
    }
  ],
  "nextCursor": "RS0xMDAxH3AtMTAwMQ"
}

POST /api/v1/people

Create a person and start the hire flow

Stages a hire through the same path as the app's People form: the same normalisation, integrity checks, configurable hire approval routing, audit event, notifications and webhooks. The person is created when the flow completes, not before. The token's creating account must still be an active HR or administrator member of the company.

Scope people:write

Headers

Idempotency-Key string

An opaque caller-chosen key, 1 to 200 characters. Replaying the same key with the same body returns the first response with replayed=true instead of creating a second change. Replaying it with a different body is a 409.

Request body

The person to hire.

businessTitle string

costCenter string

countryCode string

ISO 3166-1 alpha-2 country code.

department string required

effectiveFrom string (date) required

The employment's start date. The hire runs the company's configured hire approval flow.

employeeNumber string required

The employee's number, unique in the company.

firstName string required

grade string

initialCompensation CompensationChangeRequest

initialCompensation.amount string required

An exact decimal string, for example 62500.00. It is stored with its exact precision.

initialCompensation.currency string required

ISO 4217 currency code.

initialCompensation.effectiveFrom string (date) required

initialCompensation.employmentId string

initialCompensation.payBasis string: annual, monthly, hourly required

initialCompensation.revision integer required

jobTitle string required

lastName string required

legalEntityId string required

location string required

workEmail string (email) required

workFromHome boolean

workerType string: employee, manager, contractor

Response fields WriteResult

personId string

replayed boolean

status string required

transactionId integer required

Responses

202

The change was staged and is now in the company's configured approval flow. It is not applied until that flow completes.

400

The body, the person id, the effective date or the revision is invalid. Unknown body fields are rejected.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

409

The revision is stale, the record already exists, or the Idempotency-Key was used for a different body.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl -X POST "https://api.looma.hr/api/v1/people" \
  -H "Authorization: Bearer $LOOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "employeeNumber": "E1001",
  "firstName": "Alex",
  "lastName": "Nguyen",
  "workEmail": "alex.nguyen@example.com",
  "legalEntityId": "le-se-01",
  "jobTitle": "People Partner",
  "department": "People",
  "location": "Stockholm",
  "effectiveFrom": "2026-03-01"
}'

const response = await fetch("https://api.looma.hr/api/v1/people", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "employeeNumber": "E1001",
    "firstName": "Alex",
    "lastName": "Nguyen",
    "workEmail": "alex.nguyen@example.com",
    "legalEntityId": "le-se-01",
    "jobTitle": "People Partner",
    "department": "People",
    "location": "Stockholm",
    "effectiveFrom": "2026-03-01"
  }),
});
console.log(response.status, await response.json());

import os, requests, uuid

response = requests.post(
    "https://api.looma.hr/api/v1/people",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "employeeNumber": "E1001",
        "firstName": "Alex",
        "lastName": "Nguyen",
        "workEmail": "alex.nguyen@example.com",
        "legalEntityId": "le-se-01",
        "jobTitle": "People Partner",
        "department": "People",
        "location": "Stockholm",
        "effectiveFrom": "2026-03-01"
    },
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "employeeNumber": "E1001",
  "firstName": "Alex",
  "lastName": "Nguyen",
  "workEmail": "alex.nguyen@example.com",
  "legalEntityId": "le-se-01",
  "jobTitle": "People Partner",
  "department": "People",
  "location": "Stockholm",
  "effectiveFrom": "2026-03-01"
}`)
	req, err := http.NewRequest("POST", "https://api.looma.hr/api/v1/people", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", rand.Text())
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "personId": "p-1001",
  "status": "PENDING_APPROVAL",
  "transactionId": 4211
}

GET /api/v1/people/changes

Synchronize people incrementally

Requires people:read and a live HR/admin owner. Start without checkpoint against an empty local store; persist each page and its returned checkpoint atomically. Continue with checkpoint until hasMore=false; that checkpoint is the lossless snapshot/delta handoff. Poll it for subsequent deltas. Always use this endpoint for bootstrap, not the directory listing. Checkpoints are opaque, tenant/token/resource-bound and expire after seven days, including unfinished batches. Invalid, foreign or expired checkpoints return 410 resync_required: discard the local projection and bootstrap again. Events are retained eight days; expired metadata is removed on polling. IDs in bootstrap are frozen; delta batches have a fixed upper commit sequence and order by sequence. Apply items in response order as replacements by id; repeated identities and replay are expected. Only identities and invalidations are stored: pages project current committed fields with current field policies, so retries may contain newer values. Removed or erased or no-current-primary people return only id and action=remove; delete all locally held fields. Former employees remain upserts with person.status=Former. Backdated changes invalidate immediately; future changes may invalidate immediately and all people are invalidated on the first poll of each new company day to activate effective dates even without writes. Policy and legal-entity changes invalidate all people. A demoted owner is refused; resume after reauthorization or bootstrap with a new token. A withheld field is blank and listed in hiddenFields; replace the whole previous projection so revoked fields are deleted. Do not apply concurrent page responses out of order.

Scope people:read

Query parameters

checkpoint string

Opaque checkpoint returned by the previous page; omit only for a fresh bootstrap.

limit integer

1–200 identities per page, default 50.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields

checkpoint string required

hasMore boolean required

items array of object required

items[].action string required

items[].id string required

items[].person Employee

One employee record with the effective-dated primary employment as of the requested date. Fields denied by the integration field-visibility policy are blank and listed in hiddenFields.

items[].person.accountId string

items[].person.businessTitle string

items[].person.countryCode string

items[].person.department string required

items[].person.employeeNumber string required

items[].person.employmentId string

items[].person.firstName string required

items[].person.hasPhoto boolean

items[].person.hiddenFields array of string

items[].person.id string required

items[].person.jobTitle string required

items[].person.lastName string required

items[].person.legalEntity string required

items[].person.lifecycle string

items[].person.location string required

items[].person.revision integer required

items[].person.startDate string (date) required

items[].person.status string required

items[].person.workEmail string required

items[].person.workFromHome boolean or null

items[].person.workerType string

phase string required

Responses

200

items: ordered {id, action: upsert, person: Employee} or minimal {id, action: remove}; checkpoint: opaque string; hasMore: boolean; phase: snapshot or delta. Requires people:read and a live HR/admin owner. Start without checkpoint against an empty local store; persist each page and its returned checkpoint atomically. Continue with checkpoint until hasMore=false; that checkpoint is the lossless snapshot/delta handoff. Poll it for subsequent deltas. Always use this endpoint for bootstrap, not the directory listing. Checkpoints are opaque, tenant/token/resource-bound and expire after seven days, including unfinished batches. Invalid, foreign or expired checkpoints return 410 resync_required: discard the local projection and bootstrap again. Events are retained eight days; expired metadata is removed on polling. IDs in bootstrap are frozen; delta batches have a fixed upper commit sequence and order by sequence. Apply items in response order as replacements by id; repeated identities and replay are expected. Only identities and invalidations are stored: pages project current committed fields with current field policies, so retries may contain newer values. Removed or erased or no-current-primary people return only id and action=remove; delete all locally held fields. Former employees remain upserts with person.status=Former. Backdated changes invalidate immediately; future changes may invalidate immediately and all people are invalidated on the first poll of each new company day to activate effective dates even without writes. Policy and legal-entity changes invalidate all people. A demoted owner is refused; resume after reauthorization or bootstrap with a new token. A withheld field is blank and listed in hiddenFields; replace the whole previous projection so revoked fields are deleted. Do not apply concurrent page responses out of order.

401

Credential or membership is no longer live.

403

Missing people:read or live HR/admin role.

410

resync_required. Discard the projection and bootstrap again.

curl "https://api.looma.hr/api/v1/people/changes?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/people/changes?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/people/changes?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/people/changes?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "checkpoint": "string",
  "hasMore": false,
  "items": [
    {
      "action": "string",
      "id": "p-1001",
      "person": {
        "accountId": "string",
        "businessTitle": "People Partner",
        "countryCode": "SE",
        "department": "People",
        "employeeNumber": "E1001",
        "employmentId": "string",
        "firstName": "Alex",
        "hasPhoto": false,
        "hiddenFields": [],
        "id": "p-1001",
        "jobTitle": "People Partner",
        "lastName": "Nguyen",
        "legalEntity": "string",
        "lifecycle": "string",
        "location": "Stockholm",
        "revision": 0,
        "startDate": "2026-03-01",
        "status": "string",
        "workEmail": "string",
        "workFromHome": false,
        "workerType": "string"
      }
    }
  ],
  "phase": "string"
}

GET /api/v1/people/{person}

Read one employee record

One employee's effective-dated primary employment as of an optional date. Fields denied by the integration field-visibility policy are blank and listed in hiddenFields.

Scope people:read

Path parameters

person string required

The person id.

Query parameters

on string (date)

Effective date (YYYY-MM-DD). Defaults to today (UTC).

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

Response fields Employee

accountId string

businessTitle string

countryCode string

department string required

employeeNumber string required

employmentId string

firstName string required

hasPhoto boolean

hiddenFields array of string

id string required

jobTitle string required

lastName string required

legalEntity string required

lifecycle string

location string required

revision integer required

startDate string (date) required

status string required

workEmail string required

workFromHome boolean or null

workerType string

Responses

200

The employee record as of the requested date.

400

The effective date or person id is invalid.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

No employee matched that id on the requested date.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/people/p-1001" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/people/p-1001",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/people/p-1001", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "countryCode": "SE",
  "department": "People",
  "employeeNumber": "E-1001",
  "firstName": "Alex",
  "id": "p-1001",
  "jobTitle": "People Partner",
  "lastName": "Nguyen",
  "legalEntity": "Northwind Sweden AB",
  "location": "Stockholm",
  "revision": 1,
  "startDate": "2024-03-01",
  "status": "active",
  "workEmail": "alex.nguyen@example.test",
  "workerType": "employee"
}

GET /api/v1/people/{person}/benefits

List a person's benefit enrolments

Scope benefits:read

Path parameters

person string required

Query parameters

limit integer

cursor string

Responses

200

A tenant-scoped cursor page.

curl "https://api.looma.hr/api/v1/people/p-1001/benefits?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001/benefits?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/people/p-1001/benefits?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/people/p-1001/benefits?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/people/{person}/compensation

Read a person's compensation history

One person's effective-dated pay history and current pay as of an optional date. HR and administrator tokens only, exactly as in the app. Amounts, the pay-zone range and the market context honour the integration field-visibility policy; a denied policy blanks them and names salary in hiddenFields. Cross-tenant reads are impossible because the tenant comes only from the token.

Scope compensation:read

Path parameters

person string required

The person id.

Query parameters

on string (date)

Effective date (YYYY-MM-DD). Defaults to today (UTC).

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

Response fields CompensationRecord

current object or null required

employmentId string

hiddenFields array of string

history array of object

history[].amount string required

history[].currency string required

history[].effectiveFrom string (date) required

history[].employmentId string

history[].payBasis string required

history[].revision integer required

market object or null

oneOffPayments array of object

oneOffPayments[].amount string required

oneOffPayments[].approvedAt object or null

oneOffPayments[].createdAt object required

oneOffPayments[].currency string required

oneOffPayments[].employeeNumber string

oneOffPayments[].hiddenFields array of string

oneOffPayments[].id integer required

oneOffPayments[].kind string required

oneOffPayments[].payDate string required

oneOffPayments[].payHidden boolean

oneOffPayments[].personId string required

oneOffPayments[].personName string

oneOffPayments[].reason string

oneOffPayments[].requestedBy string

oneOffPayments[].revision integer required

oneOffPayments[].status string required

oneOffPayments[].title string required

oneOffPayments[].transactionId integer or null

oneOffPayments[].updatedAt object required

personId string required

priorPayChangePercent string

promotionLinked boolean required

revision integer required

totalCash object or null

zone object or null

Responses

200

The effective-dated pay history and current pay as of the requested date.

400

The effective date or person id is invalid.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

No employee matched that id on the requested date.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/people/p-1001/compensation" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001/compensation", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/people/p-1001/compensation",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/people/p-1001/compensation", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "current": {
    "amount": "65000.00",
    "currency": "SEK",
    "effectiveFrom": "2025-03-01",
    "employmentId": "e-1",
    "payBasis": "annual",
    "revision": 3
  },
  "employmentId": "e-1",
  "history": [
    {
      "amount": "62500.00",
      "currency": "SEK",
      "effectiveFrom": "2024-03-01",
      "employmentId": "e-1",
      "payBasis": "annual",
      "revision": 2
    }
  ],
  "personId": "p-1001",
  "revision": 3
}

POST /api/v1/people/{person}/compensation

Submit an effective-dated pay change

Stages a pay change through the same path as the app's compensation form, with the same revision check and configurable compensation-change approval routing. The amount is an exact decimal string and is stored with its exact precision. Pay is HR and administrator only, exactly as in the app.

Scope compensation:write

Path parameters

person string required

The person id.

Headers

Idempotency-Key string

An opaque caller-chosen key, 1 to 200 characters. Replaying the same key with the same body returns the first response with replayed=true instead of creating a second change. Replaying it with a different body is a 409.

Request body

The pay to change from effectiveFrom.

amount string required

An exact decimal string, for example 62500.00. It is stored with its exact precision.

currency string required

ISO 4217 currency code.

effectiveFrom string (date) required

employmentId string

payBasis string: annual, monthly, hourly required

revision integer required

Response fields WriteResult

personId string

replayed boolean

status string required

transactionId integer required

Responses

202

The change was staged and is now in the company's configured approval flow. It is not applied until that flow completes.

400

The body, the person id, the effective date or the revision is invalid. Unknown body fields are rejected.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

409

The revision is stale, the record already exists, or the Idempotency-Key was used for a different body.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl -X POST "https://api.looma.hr/api/v1/people/p-1001/compensation" \
  -H "Authorization: Bearer $LOOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "amount": "52000.00",
  "currency": "SEK",
  "payBasis": "annual",
  "effectiveFrom": "2026-03-01",
  "revision": 0
}'

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001/compensation", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "amount": "52000.00",
    "currency": "SEK",
    "payBasis": "annual",
    "effectiveFrom": "2026-03-01",
    "revision": 0
  }),
});
console.log(response.status, await response.json());

import os, requests, uuid

response = requests.post(
    "https://api.looma.hr/api/v1/people/p-1001/compensation",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "amount": "52000.00",
        "currency": "SEK",
        "payBasis": "annual",
        "effectiveFrom": "2026-03-01",
        "revision": 0
    },
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "amount": "52000.00",
  "currency": "SEK",
  "payBasis": "annual",
  "effectiveFrom": "2026-03-01",
  "revision": 0
}`)
	req, err := http.NewRequest("POST", "https://api.looma.hr/api/v1/people/p-1001/compensation", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", rand.Text())
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "personId": "p-1001",
  "status": "PENDING_APPROVAL",
  "transactionId": 4211
}

POST /api/v1/people/{person}/employment

Submit an effective-dated employment change

Stages a job, assignment or employment change through the same path as the app's employment form, including the same revision check and configurable employment-change approval routing. The change takes effect on effectiveFrom when the flow completes. HR and administrator tokens may change any person; a manager token only a current direct report.

Scope people:write

Path parameters

person string required

The person id.

Headers

Idempotency-Key string

An opaque caller-chosen key, 1 to 200 characters. Replaying the same key with the same body returns the first response with replayed=true instead of creating a second change. Replaying it with a different body is a 409.

Request body

The employment values to change from effectiveFrom.

businessTitle string

costCenter string

countryCode string

department string required

effectiveFrom string (date) required

The date this change takes effect. A past date corrects history; a future date schedules it.

employmentId string

The employment to change. Omit when the person has exactly one.

grade string

jobTitle string required

legalEntityId string required

location string required

revision integer required

The revision the caller last read. A stale revision is a conflict, never a silent overwrite.

workFromHome boolean

workerType string: employee, manager, contractor

Response fields WriteResult

personId string

replayed boolean

status string required

transactionId integer required

Responses

202

The change was staged and is now in the company's configured approval flow. It is not applied until that flow completes.

400

The body, the person id, the effective date or the revision is invalid. Unknown body fields are rejected.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

409

The revision is stale, the record already exists, or the Idempotency-Key was used for a different body.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl -X POST "https://api.looma.hr/api/v1/people/p-1001/employment" \
  -H "Authorization: Bearer $LOOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legalEntityId": "le-se-01",
  "jobTitle": "People Partner",
  "department": "People",
  "location": "Stockholm",
  "effectiveFrom": "2026-03-01",
  "revision": 0
}'

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001/employment", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "legalEntityId": "le-se-01",
    "jobTitle": "People Partner",
    "department": "People",
    "location": "Stockholm",
    "effectiveFrom": "2026-03-01",
    "revision": 0
  }),
});
console.log(response.status, await response.json());

import os, requests, uuid

response = requests.post(
    "https://api.looma.hr/api/v1/people/p-1001/employment",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "legalEntityId": "le-se-01",
        "jobTitle": "People Partner",
        "department": "People",
        "location": "Stockholm",
        "effectiveFrom": "2026-03-01",
        "revision": 0
    },
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "legalEntityId": "le-se-01",
  "jobTitle": "People Partner",
  "department": "People",
  "location": "Stockholm",
  "effectiveFrom": "2026-03-01",
  "revision": 0
}`)
	req, err := http.NewRequest("POST", "https://api.looma.hr/api/v1/people/p-1001/employment", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", rand.Text())
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "personId": "p-1001",
  "status": "PENDING_APPROVAL",
  "transactionId": 4211
}

GET /api/v1/people/{person}/history

Read a person's lifecycle history

Scope lifecycle:read

Path parameters

person string required

Query parameters

limit integer

cursor string

Responses

200

A cursor-paginated lifecycle history.

curl "https://api.looma.hr/api/v1/people/p-1001/history?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001/history?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/people/p-1001/history?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/people/p-1001/history?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/people/{person}/reviews

List a person's review assignments

Scope performance:read

Path parameters

person string required

Query parameters

limit integer

Page size (1–200; default 50).

cursor string

Opaque nextCursor from the previous page.

Responses

200

A cursor-paginated page of visible review cycles or reviews.

curl "https://api.looma.hr/api/v1/people/p-1001/reviews?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001/reviews?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/people/p-1001/reviews?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/people/p-1001/reviews?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/performance/reviews

List review cycles

Scope performance:read

Query parameters

limit integer

Page size (1–200; default 50).

cursor string

Opaque nextCursor from the previous page.

Responses

200

A cursor-paginated page of visible review cycles or reviews.

curl "https://api.looma.hr/api/v1/performance/reviews?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/performance/reviews?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/performance/reviews?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/performance/reviews?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/employees/{person}/goals

List an employee's visible current goals

Scope objectives:read

Path parameters

person string required

Query parameters

limit integer

Page size (1–200; default 50).

cursor string

Opaque nextCursor from the previous page.

Responses

200

A cursor-paginated page of visible current-cycle objectives.

curl "https://api.looma.hr/api/v1/employees/p-1001/goals?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/employees/p-1001/goals?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/employees/p-1001/goals?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/employees/p-1001/goals?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/employees/{person}/objectives

List an employee's current-cycle objectives

Scope objectives:read

Path parameters

person string required

Query parameters

limit integer

Page size (1–200; default 50).

cursor string

Opaque nextCursor from the previous page.

Responses

200

A cursor-paginated page of visible current-cycle objectives.

curl "https://api.looma.hr/api/v1/employees/p-1001/objectives?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/employees/p-1001/objectives?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/employees/p-1001/objectives?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/employees/p-1001/objectives?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/goals

List visible current goals

Scope objectives:read

Query parameters

limit integer

Page size (1–200; default 50).

cursor string

Opaque nextCursor from the previous page.

Responses

200

A cursor-paginated page of visible current-cycle objectives.

curl "https://api.looma.hr/api/v1/goals?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/goals?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/goals?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/goals?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/objectives

List current-cycle objectives

Scope objectives:read

Query parameters

limit integer

Page size (1–200; default 50).

cursor string

Opaque nextCursor from the previous page.

Responses

200

A cursor-paginated page of visible current-cycle objectives.

curl "https://api.looma.hr/api/v1/objectives?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/objectives?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/objectives?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/objectives?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/organisation

Read the organisation

Legal entities, the active workforce catalogue (up to 1000 entries) and the current reporting line per person, keyset-paginated by person id in groups of up to 500.

Scope org:read

Query parameters

cursor string

Opaque reporting-line cursor: the last person id from the previous response. Omit for the first page.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

Response fields OrganisationResponse

catalogue array of OrganisationCatalogueEntry required

catalogue[].code string required

catalogue[].id string required

catalogue[].kind string required

catalogue[].name string required

legalEntities array of LegalEntity required

legalEntities[].id string required

legalEntities[].name string required

reportingLines array of OrganisationReportingLine required

reportingLines[].effectiveFrom string (date) required

reportingLines[].managerId string

reportingLines[].personId string required

Responses

200

The organisation snapshot.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/organisation" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/organisation", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/organisation",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/organisation", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "catalogue": [
    {
      "code": "PEOPLE",
      "id": "dep-1",
      "kind": "department",
      "name": "People"
    }
  ],
  "legalEntities": [
    {
      "id": "le-1",
      "name": "Northwind Sweden AB"
    }
  ],
  "reportingLines": [
    {
      "effectiveFrom": "2025-01-01",
      "managerId": "p-1000",
      "personId": "p-1001"
    }
  ]
}

POST /api/v1/people/{person}/manager

Submit an effective-dated reporting-line change

Stages a manager change through the same path as the app's manager-change form, with the same revision check and configurable manager-change approval routing. An empty managerId removes the line manager. HR and administrator tokens may change any person; a manager token only a current direct report.

Scope org:write

Path parameters

person string required

The person id.

Headers

Idempotency-Key string

An opaque caller-chosen key, 1 to 200 characters. Replaying the same key with the same body returns the first response with replayed=true instead of creating a second change. Replaying it with a different body is a 409.

Request body

The reporting line to change from effectiveFrom.

effectiveFrom string (date) required

expectedRevision integer required

The reporting-line revision the caller last read.

managerId string required

The new line manager's person id. An empty string removes the line manager.

Response fields WriteResult

personId string

replayed boolean

status string required

transactionId integer required

Responses

202

The change was staged and is now in the company's configured approval flow. It is not applied until that flow completes.

400

The body, the person id, the effective date or the revision is invalid. Unknown body fields are rejected.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

409

The revision is stale, the record already exists, or the Idempotency-Key was used for a different body.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl -X POST "https://api.looma.hr/api/v1/people/p-1001/manager" \
  -H "Authorization: Bearer $LOOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "managerId": "p-1042",
  "effectiveFrom": "2026-03-01",
  "expectedRevision": 0
}'

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001/manager", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "managerId": "p-1042",
    "effectiveFrom": "2026-03-01",
    "expectedRevision": 0
  }),
});
console.log(response.status, await response.json());

import os, requests, uuid

response = requests.post(
    "https://api.looma.hr/api/v1/people/p-1001/manager",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "managerId": "p-1042",
        "effectiveFrom": "2026-03-01",
        "expectedRevision": 0
    },
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "managerId": "p-1042",
  "effectiveFrom": "2026-03-01",
  "expectedRevision": 0
}`)
	req, err := http.NewRequest("POST", "https://api.looma.hr/api/v1/people/p-1001/manager", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", rand.Text())
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "personId": "p-1001",
  "status": "PENDING_APPROVAL",
  "transactionId": 4211
}

GET /api/v1/positions

List organisation positions

Scope org:read

Query parameters

limit integer

Page size (1–200; default 50).

cursor string

Opaque nextCursor from the previous page.

Responses

200

A cursor-paginated page.

curl "https://api.looma.hr/api/v1/positions?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/positions?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/positions?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/positions?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/teams

List organisation teams

Scope org:read

Query parameters

limit integer

Page size (1–200; default 50).

cursor string

Opaque nextCursor from the previous page.

Responses

200

A cursor-paginated page.

curl "https://api.looma.hr/api/v1/teams?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/teams?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/teams?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/teams?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK

GET /api/v1/time-off

List approved time off

Approved, uncancelled time-off requests, newest first by transaction id. Pass nextCursor back as cursor unchanged.

Scope timeoff:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor (transaction id) from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields TimeOffPage

hasMore boolean required

items array of TimeOffRequest required

items[].endDate string (date) required

items[].halfDay boolean required

items[].personId string required

items[].planId string required

items[].startDate string (date) required

items[].transactionId integer required

items[].units integer required

nextCursor string

Responses

200

A cursor page of leave requests.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/time-off?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/time-off?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/time-off?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/time-off?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": true,
  "items": [
    {
      "endDate": "2026-07-10",
      "halfDay": false,
      "personId": "p-1001",
      "planId": "plan-annual",
      "startDate": "2026-07-01",
      "transactionId": 42,
      "units": 8
    }
  ],
  "nextCursor": "41"
}

GET /api/v1/timecards

List approved timecards

Approved timecards, newest first by id. Pass nextCursor back as cursor unchanged.

Scope timecards:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor (timecard id) from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields TimecardPage

hasMore boolean required

items array of Timecard required

items[].id integer required

items[].periodEnd string (date) required

items[].periodStart string (date) required

items[].personId string required

items[].status string required

items[].totalMinutes integer required

items[].transactionId integer or null

nextCursor string

Responses

200

A cursor page of timecards.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/timecards?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/timecards?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/timecards?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/timecards?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": false,
  "items": [
    {
      "id": 5001,
      "periodEnd": "2026-06-15",
      "periodStart": "2026-06-01",
      "personId": "p-1001",
      "status": "approved",
      "totalMinutes": 4800,
      "transactionId": 42
    }
  ]
}

GET /api/v1/payroll/inputs

List payroll inputs

The approved pay inputs that feed each payroll run (approved timecard minutes, approved flexible-benefit amounts and approved-unpaid leave units), newest first by run id. Values are withheld and redacted is set when the integration viewer's field policy restricts compensation. Pass nextCursor back as cursor unchanged.

Scope payroll:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor (run id) from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields PayrollInputPage

hasMore boolean required

items array of PayrollInput required

items[].flexAmount string

items[].leaveUnits string

items[].redacted boolean

items[].runId integer required

items[].timecardMinutes string

nextCursor string

Responses

200

A cursor page of payroll inputs.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/payroll/inputs?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/payroll/inputs?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/payroll/inputs?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/payroll/inputs?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": true,
  "items": [
    {
      "flexAmount": "2500.0000",
      "leaveUnits": "8",
      "runId": 7001,
      "timecardMinutes": "4800.0000"
    }
  ],
  "nextCursor": "7001"
}

GET /api/v1/payroll/runs

List payroll runs

Payroll runs, newest first by run id. Totals are withheld and totalsRedacted is set when the integration viewer's field policy restricts compensation. Pass nextCursor back as cursor unchanged.

Scope payroll:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor (run id) from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields PayrollRunPage

hasMore boolean required

items array of PayrollRun required

items[].approvedAt string

items[].id integer required

items[].legalEntityId string required

items[].legalEntityName string

items[].lineCount integer required

items[].periodEnd string (date) required

items[].periodId integer required

items[].periodStart string (date) required

items[].revision integer required

items[].runKind string

items[].status string required

items[].totalGross string

items[].totalPayout string

items[].totalsRedacted boolean

nextCursor string

Responses

200

A cursor page of payroll runs.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/payroll/runs?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/payroll/runs?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/payroll/runs?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/payroll/runs?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": true,
  "items": [
    {
      "id": 7001,
      "legalEntityId": "le-1",
      "legalEntityName": "Northwind Sweden AB",
      "lineCount": 12,
      "periodEnd": "2026-06-30",
      "periodId": 410,
      "periodStart": "2026-06-01",
      "runKind": "regular",
      "status": "approved",
      "totalGross": "120000.0000",
      "totalPayout": "96000.0000"
    }
  ],
  "nextCursor": "7001"
}

GET /api/v1/payroll/runs/{run}/payslips

List a payroll run's payslips

Metadata of the published payslips in the run's payroll period, newest first. The confidential PDF bytes never appear in a paged list. Pass nextCursor back as cursor unchanged.

Scope payroll:read

Path parameters

run integer required

The payroll run id.

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor (payslip sequence) from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields PayslipPage

hasMore boolean required

items array of Payslip required

items[].byteSize integer required

items[].filename string required

items[].id string required

items[].personId string required

items[].publishedAt string

items[].status string required

items[].version integer required

nextCursor string

Responses

200

A cursor page of payslip metadata.

400

The run id or cursor is invalid.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

No payroll run matched that id.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/payroll/runs/run-2026-03/payslips?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/payroll/runs/run-2026-03/payslips?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/payroll/runs/run-2026-03/payslips?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/payroll/runs/run-2026-03/payslips?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": false,
  "items": [
    {
      "byteSize": 20480,
      "filename": "payslip-june.pdf",
      "id": "ps-1001",
      "personId": "p-1001",
      "publishedAt": "2026-07-01T08:00:00",
      "status": "published",
      "version": 1
    }
  ],
  "nextCursor": "17"
}

GET /api/v1/applications

List vacancy applications

Vacancy applications by existing people, newest first by id. Pass nextCursor back as cursor unchanged.

Scope recruiting:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields ApplicationPage

hasMore boolean required

items array of Application required

items[].coverNote string

items[].createdAt string required

items[].id integer required

items[].personId string required

items[].status string required

items[].updatedAt string required

items[].vacancyId integer required

nextCursor string

Responses

200

A cursor page of applications.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/applications?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/applications?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/applications?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/applications?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": false,
  "items": [
    {
      "id": 1101,
      "personId": "p-1001",
      "status": "submitted",
      "vacancyId": 5001
    }
  ],
  "nextCursor": "1101"
}

GET /api/v1/candidates

List candidates

Candidate contact records, newest first by id. Candidate personal fields pass the integration field-visibility policy and are blank (and listed in hiddenFields) where that policy denies them. Pass nextCursor back as cursor unchanged.

Scope recruiting:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields CandidatePage

hasMore boolean required

items array of Candidate required

items[].createdAt string required

items[].email string required

items[].firstName string required

items[].hiddenFields array of string

items[].id integer required

items[].lastName string required

items[].notes string

items[].phone string

items[].source string

items[].stage string required

items[].updatedAt string required

nextCursor string

Responses

200

A cursor page of candidates.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/candidates?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/candidates?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/candidates?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/candidates?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": false,
  "items": [
    {
      "email": "alex@example.test",
      "firstName": "Alex",
      "id": 9001,
      "lastName": "Nguyen",
      "stage": "interview"
    }
  ],
  "nextCursor": "9001"
}

GET /api/v1/jobs

List jobs (vacancies)

Vacancies, newest first by id, with their opening date, closing date and current state. Pass nextCursor back as cursor unchanged.

Scope recruiting:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields RecruitingJobPage

hasMore boolean required

items array of RecruitingJob required

items[].closingDate string

items[].createdAt string required

items[].department string

items[].description string

items[].id integer required

items[].openingDate string required

items[].status string required

items[].title string required

items[].updatedAt string required

nextCursor string

Responses

200

A cursor page of jobs.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/jobs?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/jobs?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/jobs?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/jobs?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": true,
  "items": [
    {
      "department": "People",
      "id": 5001,
      "openingDate": "2026-03-01",
      "status": "open",
      "title": "People Partner"
    }
  ],
  "nextCursor": "5001"
}

POST /api/v1/expense-receipts

Receive an expense receipt

Delivers one receipt attachment as a private proposal for the employee identified by an enabled routing token. The bearer token determines the company. Retries with the same deliveryKey return the existing intake id. This does not submit an expense claim. The JSON body is limited to 14 MiB and the decoded PDF, PNG or JPEG attachment to 10 MiB.

Scope expenses:receive

Request body

The recipient routing token, stable delivery key, filename and base64 attachment content.

content string (byte) required

Base64-encoded PDF, PNG or JPEG attachment, at most 10 MiB after decoding.

deliveryKey string required

Stable key per attachment, 1 to 200 characters. Retries return the original intake id.

filename string required

Attachment filename, 1 to 180 characters, without path separators.

routingToken string required

The employee's enabled 64-character hexadecimal recipient capability.

Response fields

intakeId string required

status string: draft required

Responses

202

The receipt was captured, or an existing delivery was replayed.

400

The receipt delivery or attachment is invalid.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

409

The employee has reached the pending receipt limit.

413

The request body exceeds the 14 MiB limit.

429

The per-token rate limit was exceeded. Retry after the current rolling minute.

503

The integration API is temporarily unavailable.

curl -X POST "https://api.looma.hr/api/v1/expense-receipts" \
  -H "Authorization: Bearer $LOOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "routingToken": "string",
  "deliveryKey": "string",
  "filename": "string",
  "content": "string"
}'

const response = await fetch("https://api.looma.hr/api/v1/expense-receipts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "routingToken": "string",
    "deliveryKey": "string",
    "filename": "string",
    "content": "string"
  }),
});
console.log(response.status, await response.json());

import os, requests

response = requests.post(
    "https://api.looma.hr/api/v1/expense-receipts",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    json={
        "routingToken": "string",
        "deliveryKey": "string",
        "filename": "string",
        "content": "string"
    },
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "routingToken": "string",
  "deliveryKey": "string",
  "filename": "string",
  "content": "string"
}`)
	req, err := http.NewRequest("POST", "https://api.looma.hr/api/v1/expense-receipts", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "intakeId": "receipt-1001",
  "status": "draft"
}

GET /api/v1/expenses

List expense claims

Employee expense claims, newest first by id. The claimant's name is blank and listed in hiddenFields when the integration field-visibility policy denies it. Totals are per currency and exact. Pass nextCursor back as cursor unchanged.

Scope expenses:read

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor (claim id) from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields ExpenseClaimPage

hasMore boolean required

items array of ExpenseClaim required

items[].createdAt string required

items[].employeeNumber string

items[].hiddenFields array of string

items[].id integer required

items[].lineCount integer required

items[].personId string required

items[].personName string

items[].revision integer required

items[].status string required

items[].title string required

items[].totals array of object required

items[].totals[].currency string required

items[].totals[].total string required

items[].updatedAt string required

nextCursor string

Responses

200

A cursor page of expense claims.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/expenses?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/expenses?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/expenses?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/expenses?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": true,
  "items": [
    {
      "employeeNumber": "E-1001",
      "id": 8201,
      "lineCount": 2,
      "personId": "p-1001",
      "personName": "Alex Nguyen",
      "revision": 2,
      "status": "pending",
      "title": "Client lunch"
    }
  ],
  "nextCursor": "8201"
}

POST /api/v1/expenses

Submit an expense claim

Creates a new expense claim for the token's linked employee and submits it through the same path as the app's claim form: the same normalisation, integrity checks, configurable EXPENSE_CLAIM approval routing, audit event and webhooks. The claim enters the company's approval flow and is not reimbursed until that flow completes. Replaying the same Idempotency-Key with the same body returns the first response instead of submitting a second claim.

Scope expenses:write

Headers

Idempotency-Key string

An opaque caller-chosen key, 1 to 200 characters. Replaying the same key with the same body returns the first response with replayed=true instead of creating a second claim. Replaying it with a different body is a 409.

Request body

The claim title and line items.

lines array of object required

At least one line item (up to 50).

lines[].amount string required

The exact amount, up to four decimal digits.

lines[].categoryId integer required

lines[].currency string required

ISO 4217 three-letter currency code.

lines[].description string

lines[].expenseDate string (date) required

lines[].merchant string required

title string required

The claim's title, 1 to 160 characters.

Response fields WriteResult

personId string

replayed boolean

status string required

transactionId integer required

Responses

202

The claim was staged and is now in the company's configured EXPENSE_CLAIM approval flow.

400

The body or the claim inputs are invalid. Unknown body fields are rejected.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

409

The Idempotency-Key was used for a different body, or the claim could not be submitted in the expected state.

429

The per-token rate limit was exceeded. Retry after the current rolling minute.

503

The integration API is temporarily unavailable.

curl -X POST "https://api.looma.hr/api/v1/expenses" \
  -H "Authorization: Bearer $LOOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "string",
  "lines": [
    {
      "expenseDate": "2026-03-01",
      "categoryId": 0,
      "merchant": "string",
      "currency": "SEK",
      "amount": "52000.00"
    }
  ]
}'

const response = await fetch("https://api.looma.hr/api/v1/expenses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "title": "string",
    "lines": [
      {
        "expenseDate": "2026-03-01",
        "categoryId": 0,
        "merchant": "string",
        "currency": "SEK",
        "amount": "52000.00"
      }
    ]
  }),
});
console.log(response.status, await response.json());

import os, requests, uuid

response = requests.post(
    "https://api.looma.hr/api/v1/expenses",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "title": "string",
        "lines": [
            {
                "expenseDate": "2026-03-01",
                "categoryId": 0,
                "merchant": "string",
                "currency": "SEK",
                "amount": "52000.00"
            }
        ]
    },
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "title": "string",
  "lines": [
    {
      "expenseDate": "2026-03-01",
      "categoryId": 0,
      "merchant": "string",
      "currency": "SEK",
      "amount": "52000.00"
    }
  ]
}`)
	req, err := http.NewRequest("POST", "https://api.looma.hr/api/v1/expenses", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", rand.Text())
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "personId": "p-1001",
  "status": "PENDING_APPROVAL",
  "transactionId": 9211
}

GET /api/v1/expenses/{claim}

Read one expense claim

One expense claim with its full line items and event history. The claimant's name is blank and listed in hiddenFields when the integration field-visibility policy denies it.

Scope expenses:read

Path parameters

claim integer required

The claim id.

Query parameters

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

Response fields ExpenseClaimDetail

claim ExpenseClaim required

One expense claim with its headers and per-currency totals. The claimant's name is blank and listed in hiddenFields under the integration field-visibility policy.

claim.createdAt string required

claim.employeeNumber string

claim.hiddenFields array of string

claim.id integer required

claim.lineCount integer required

claim.personId string required

claim.personName string

claim.revision integer required

claim.status string required

claim.title string required

claim.totals array of object required

claim.totals[].currency string required

claim.totals[].total string required

claim.updatedAt string required

events array of object

events[].actorId string

events[].body string

events[].createdAt string required

events[].id integer required

events[].kind string required

lines array of object required

lines[].amount string required

lines[].category string

lines[].categoryId integer required

lines[].currency string required

lines[].description string

lines[].expenseDate string required

lines[].id integer required

lines[].merchant string required

totals array of object required

totals[].currency string required

totals[].total string required

transactionId integer or null

Responses

200

The claim and its lines.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

No expense claim matched that id.

429

The per-token rate limit was exceeded. Retry after the current rolling minute.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/expenses/exp-3101" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/expenses/exp-3101", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/expenses/exp-3101",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/expenses/exp-3101", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "claim": {
    "id": 8201,
    "lineCount": 2,
    "personId": "p-1001",
    "personName": "Alex Nguyen",
    "revision": 2,
    "status": "pending",
    "title": "Client lunch"
  }
}

GET /api/v1/people/{person}/documents

List employee documents

Employee document metadata for a person, newest first by id. The document bytes are not returned by this endpoint; use the download endpoint in the self-service API for file access. Employee fields pass the integration field-visibility policy. Pass nextCursor back as cursor unchanged.

Scope documents:read

Path parameters

person string required

The person id.

Query parameters

limit integer

Maximum number of items to return. Values above the maximum are clamped.

cursor string

Opaque keyset cursor (document id) from a previous response's nextCursor.

fields string

Comma-separated top-level properties to return for each record, for example fields=id,firstName,workEmail. A page's items, nextCursor and hasMore and each record's hiddenFields are always returned. A name this resource does not carry is a 400.

include string

Comma-separated nested collections to return, for example include=reportingLines. Naming one keeps it and drops the answer's other collections; it never adds data the endpoint would not otherwise return. A name this resource does not carry is a 400.

filter string

Comma-separated field:value matches, all of which must hold, for example filter=status:active,department:People. It narrows the items of the page this read returns, so a filtered page may be shorter than limit; nextCursor still continues the collection. A field this resource does not carry, or a malformed match, is a 400.

sort string

Comma-separated fields to order the returned page by, descending for a field prefixed with '-', for example sort=-startDate,lastName. It orders the items of the page; the collection's own order still governs which rows the page contains and how nextCursor continues it. A field this resource does not carry is a 400.

page integer

The 1-based page of the collection to return, up to the maximum. It is the cursor-free way to traverse a collection: the answer is this read's own answer for that page, with its own nextCursor and hasMore. Page N reads the collection N times, so it spends N of the token's request budget and issues N queries; a client traversing many pages should pass nextCursor back as cursor instead. It cannot be combined with cursor. A page past the collection's last one is an empty page.

Response fields EmployeeDocumentPage

hasMore boolean required

items array of EmployeeDocument required

items[].archived boolean required

items[].byteSize integer required

items[].category string required

items[].contentType string required

items[].createdAt string required

items[].employeeVisible boolean required

items[].filename string required

items[].hiddenFields array of string

items[].id string required

items[].personId string required

items[].revision integer required

items[].title string required

items[].uploadedBy string required

nextCursor string

Responses

200

A cursor page of employee document metadata.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

429

The per-token rate limit was exceeded. Retry after the current rolling minute.

503

The integration API is temporarily unavailable.

curl "https://api.looma.hr/api/v1/people/p-1001/documents?limit=2" \
  -H "Authorization: Bearer $LOOMA_TOKEN"

const response = await fetch("https://api.looma.hr/api/v1/people/p-1001/documents?limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
  },
});
console.log(response.status, await response.json());

import os, requests

response = requests.get(
    "https://api.looma.hr/api/v1/people/p-1001/documents?limit=2",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/people/p-1001/documents?limit=2", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "hasMore": true,
  "items": [
    {
      "archived": false,
      "byteSize": 102400,
      "category": "employment",
      "contentType": "application/pdf",
      "createdAt": "2026-01-15T10:30:00Z",
      "employeeVisible": true,
      "filename": "contract.pdf",
      "id": "doc-1001",
      "personId": "p-1001",
      "revision": 1,
      "title": "Employment Contract",
      "uploadedBy": "hr-account"
    }
  ],
  "nextCursor": "doc-1001"
}

POST /api/v1/webhooks/{webhook}/deliveries/replay

Replay webhook deliveries from the delivery log

Re-enqueues the exact stored payload of every delivery to this endpoint in the date range, bounded to the last 30 days. Receivers deduplicate replayed deliveries on the X-Looma-Delivery header. Administrator tokens only; this is integration administration, not an HR action.

Scope webhooks:write

Path parameters

webhook string required

The webhook endpoint id.

Headers

Idempotency-Key string

An opaque caller-chosen key, 1 to 200 characters. Replaying the same key with the same body returns the first response with replayed=true instead of creating a second change. Replaying it with a different body is a 409.

Request body

The inclusive date range to replay.

from string (date) required

First delivery date to replay, within the last 30 days.

until string (date) required

Last delivery date to replay, inclusive. Today or earlier.

Responses

200

The number of deliveries re-enqueued.

400

The body, the person id, the effective date or the revision is invalid. Unknown body fields are rejected.

401

Missing, malformed or unknown token. Every authentication failure returns the same message.

403

The token does not include the scope this endpoint requires.

404

The company workspace host does not match the token's company.

409

The revision is stale, the record already exists, or the Idempotency-Key was used for a different body.

429

The per-token rate limit was exceeded. Retry after the current rolling minute. The budget is 600 read or 60 write requests per token in one rolling 1m0s.

503

The integration API is temporarily unavailable.

curl -X POST "https://api.looma.hr/api/v1/webhooks/wh-201/deliveries/replay" \
  -H "Authorization: Bearer $LOOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "from": "2026-03-01",
  "until": "2026-03-01"
}'

const response = await fetch("https://api.looma.hr/api/v1/webhooks/wh-201/deliveries/replay", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "from": "2026-03-01",
    "until": "2026-03-01"
  }),
});
console.log(response.status, await response.json());

import os, requests, uuid

response = requests.post(
    "https://api.looma.hr/api/v1/webhooks/wh-201/deliveries/replay",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "from": "2026-03-01",
        "until": "2026-03-01"
    },
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "from": "2026-03-01",
  "until": "2026-03-01"
}`)
	req, err := http.NewRequest("POST", "https://api.looma.hr/api/v1/webhooks/wh-201/deliveries/replay", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", rand.Text())
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "replayed": 12
}

POST /api/v1/automation-sources/{source}/events

Submit a typed external business event

Maximum 4096 bytes. The source must bind this bearer token and event type. An explicit employee-number/person mapping must still match the tenant record. externalEventId is idempotent per source; conflicting duplicates return 409. Accepted active subscriptions are pinned to their rule version. Revocation cancels pending deliveries. Activating a rule never replays old events. Operators can inspect deliveries and request a bounded replay through the source management API.

Scope automations.events:write

Path parameters

source string required

Request body

Only these five fields are accepted.

employeeNumber string required

eventType string: service_desk_cleared, training_completed, compliance_check_completed required

externalEventId string required

occurredAt string (date-time) required

sourceRecordId string required

Responses

202

Persisted event receipt (id and duplicate); execution is asynchronous.

400

Invalid type, schema, timestamp or oversized body.

401

Invalid bearer credential.

403

Missing scope, revoked or unbound source, or denied employee mapping.

409

External event ID already has a different payload.

curl -X POST "https://api.looma.hr/api/v1/automation-sources/src-7/events" \
  -H "Authorization: Bearer $LOOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "externalEventId": "string",
  "eventType": "service_desk_cleared",
  "sourceRecordId": "string",
  "employeeNumber": "E1001",
  "occurredAt": "2026-03-01T09:00:00Z"
}'

const response = await fetch("https://api.looma.hr/api/v1/automation-sources/src-7/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOMA_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "externalEventId": "string",
    "eventType": "service_desk_cleared",
    "sourceRecordId": "string",
    "employeeNumber": "E1001",
    "occurredAt": "2026-03-01T09:00:00Z"
  }),
});
console.log(response.status, await response.json());

import os, requests

response = requests.post(
    "https://api.looma.hr/api/v1/automation-sources/src-7/events",
    headers={"Authorization": f"Bearer {os.environ['LOOMA_TOKEN']}"},
    json={
        "externalEventId": "string",
        "eventType": "service_desk_cleared",
        "sourceRecordId": "string",
        "employeeNumber": "E1001",
        "occurredAt": "2026-03-01T09:00:00Z"
    },
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "externalEventId": "string",
  "eventType": "service_desk_cleared",
  "sourceRecordId": "string",
  "employeeNumber": "E1001",
  "occurredAt": "2026-03-01T09:00:00Z"
}`)
	req, err := http.NewRequest("POST", "https://api.looma.hr/api/v1/automation-sources/src-7/events", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LOOMA_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 202 Accepted

GET /api/v1/changelog

Published release record of this API

Returns the contract releases, newest first, with the current version, so an integration can reconcile against the X-API-Version header it was served. It carries no tenant data and needs no token.

No token

Responses

200

The published release record.

curl "https://api.looma.hr/api/v1/changelog"

const response = await fetch("https://api.looma.hr/api/v1/changelog");
console.log(response.status, await response.json());

import requests

response = requests.get(
    "https://api.looma.hr/api/v1/changelog",
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/changelog", nil)
	if err != nil {
		panic(err)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

{
  "apiVersion": "1.0.0",
  "current": {
    "version": "1.0.0",
    "date": "2026-10-14",
    "title": "Every response names the contract version, and the release record is published",
    "body": "Every response from the versioned API now carries the X-API-Version header naming the semver contract release that produced it, and GET /api/v1/changelog publishes this release record, so an integration can see which contract era it is running against and what changed since. The first public release of the versioned API ships in this same era: scoped bearer tokens, field visibility applied per person, keyset pagination, per-token rate limiting and HMAC-signed outbound webhooks, with the write surface staging a hire, an employment, a reporting-line and a pay change under an Idempotency-Key."
  },
  "entries": [
    {
      "version": "1.0.0",
      "date": "2026-10-14",
      "title": "Every response names the contract version, and the release record is published",
      "body": "Every response from the versioned API now carries the X-API-Version header naming the semver contract release that produced it, and GET /api/v1/changelog publishes this release record, so an integration can see which contract era it is running against and what changed since. The first public release of the versioned API ships in this same era: scoped bearer tokens, field visibility applied per person, keyset pagination, per-token rate limiting and HMAC-signed outbound webhooks, with the write surface staging a hire, an employment, a reporting-line and a pay change under an Idempotency-Key."
    }
  ]
}

GET /api/v1/collections/bruno.json

Download the Bruno request collection

The whole /api/v1 surface as a Bruno collection, generated from this document. It carries no credential: the base URL and the bearer token are collection variables the developer fills in.

No token

Responses

200

A Bruno 1.x collection document.

curl "https://api.looma.hr/api/v1/collections/bruno.json"

const response = await fetch("https://api.looma.hr/api/v1/collections/bruno.json");
console.log(response.status, await response.json());

import requests

response = requests.get(
    "https://api.looma.hr/api/v1/collections/bruno.json",
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/collections/bruno.json", nil)
	if err != nil {
		panic(err)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK
Content-Type: application/json

GET /api/v1/collections/postman.json

Download the Postman request collection

The whole /api/v1 surface as a Postman 2.1 collection, generated from this document with the same requests as the Bruno collection. It carries no credential.

No token

Responses

200

A Postman 2.1 collection document.

curl "https://api.looma.hr/api/v1/collections/postman.json"

const response = await fetch("https://api.looma.hr/api/v1/collections/postman.json");
console.log(response.status, await response.json());

import requests

response = requests.get(
    "https://api.looma.hr/api/v1/collections/postman.json",
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/collections/postman.json", nil)
	if err != nil {
		panic(err)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK
Content-Type: application/json

GET /api/v1/openapi.json

OpenAPI 3.1 description of this API

Returns this document. It carries no tenant data and needs no token, so tooling and the admin developer-docs page can read the contract.

No token

Responses

200

The OpenAPI 3.1 document.

curl "https://api.looma.hr/api/v1/openapi.json"

const response = await fetch("https://api.looma.hr/api/v1/openapi.json");
console.log(response.status, await response.json());

import requests

response = requests.get(
    "https://api.looma.hr/api/v1/openapi.json",
    timeout=30,
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.looma.hr/api/v1/openapi.json", nil)
	if err != nil {
		panic(err)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(data))
}

HTTP/1.1 200 OK
Content-Type: application/json