Skip to main content
GET
List job-positions
This API endpoint is in beta and may be subject to changes, including breaking changes (similarly to the legacy API endpoints), without prior notice. Read more about versioning.
Working-time arrangements are an opt-in feature. You may not benefit from this feature. Working-time-arrangements are the replacement for the workcycles. If this feature has not been deployed on your environment, please contact our support.
OAuth 2.0 scopes
or
EstablishmentsThis API endpoint will filter out results based on accessible business-establishments.You may only access job-positions belonging to employees whose applicable business-establishments are accessible to you.

Authorizations

​
Authorization
string
header
required

The Lucca API implements the oAuth 2 protocol with the client-credentials-flow. Refer to RFC8725.

FlowClient Credentials
Token URL
https://accounts.world.luccasoftware.com/connect/token
Scopes1
job-positions.readonly
Read [job-positions](/api-reference/latest/employments/job-position).

Headers

​
Api-Version
enum<string>
required

Set the API version.

Available options:
2024-11-01
Allowed value: "2024-11-01"
Maximum string length: 10
Example:

"2024-11-01"

​
If-None-Match
string

Only execute the request if current cached version of the resource does not match the one given here.

Example:

"W/q5sd4w2x1c1gfdg"

​
If-Match
string

Only execute the request if current cached version of the resource matches the one given here. Useful to avoid concurrency conflicts.

Example:

"W/q5sd4w2x1c1gfdg"

​
Accept-Encoding
string

List of compression algorithms you support.

Query Parameters

​
id
string[]

Filter out job-positions on their IDs. Comma-separated list of strings.

Maximum array length: 100
Minimum string length: 1
Example:
​
remoteId
string[]

Filter out job-positions on their remoteId. Comma-separated list of strings.

Maximum array length: 100
Minimum string length: 1
Example:
​
employment.id
string[]

Filter out job-positions on their employment IDs. Comma-separated list of strings.

Maximum array length: 100
Minimum string length: 1
Example:
​
businessEstablishment.id
string[]

Filter out job-positions on their business-establishment IDs. Comma-separated list of strings.

Maximum array length: 100
Minimum string length: 1
Example:
​
status
enum<string>

Filter out employments on their status. Read-only. The employee status is calculated from the employee's employments.

  • active: employee has an employment as of today.
  • upcoming: employee currently has no employment but will have one in the future.
  • deactivated: employee used to have an employment but no longer does.
Available options:
active,
upcoming,
deactivated
Example:

"active"

​
startsOn
string<date>

Filter out job-positions on their startsOn date (strict equality).

​
startsOn.between
string

Filter out job-positions on their startsOn date (range). ISO 8601 formatted date-range string. ISO 8601 formatted date-range string. Examples:

  • 2024-01-01--2024-12-31: from Jan. 1st 2024 until Dec. 31st 2024 (included).
  • ..--2024-12-31: until Dec. 31st 2024.
  • 2024-01-01--..: from Jan. 1st 2024.
Pattern: ^(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])|\.\.)--(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])|\.\.)$
Examples:

"2024-01-01--2024-12-31"

"..--2024-12-31"

"2024-01-01--.."

​
endsOn

Filter out job-positions on their endsOn date (strict equality).

​
endsOn.between
string

Filter out job-positions on their endsOn date (range). ISO 8601 formatted date-range string. ISO 8601 formatted date-range string. Examples:

  • 2024-01-01--2024-12-31: from Jan. 1st 2024 until Dec. 31st 2024 (included).
  • ..--2024-12-31: until Dec. 31st 2024.
  • 2024-01-01--..: from Jan. 1st 2024.
Pattern: ^(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])|\.\.)--(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])|\.\.)$
Examples:

"2024-01-01--2024-12-31"

"..--2024-12-31"

"2024-01-01--.."

​
jobQualification.id
string[]

Filter out job-positions on their job-qualification IDs. Comma-separated list of strings.

Maximum array length: 100
Minimum string length: 1
Example:
​
occupationCategory.id
string[]

Filter out job-positions on their occupation-category IDs. Comma-separated list of strings.

Maximum array length: 100
Minimum string length: 1
Example:
​
manager.id
string[]

Filter out job-positions on their manager IDs. Comma-separated list of strings.

Maximum array length: 100
Minimum string length: 1
Example:
​
department.id
string[]

Filter out job-positions on their department IDs. Comma-separated list of strings.

Maximum array length: 100
Minimum string length: 1
Example:
​
updatedAttributes
enum<string>[]

Only return job-positions that changed one of the given attributes.

Maximum array length: 100

List of attributes that can change for a job-position.

Available options:
remoteId,
businessEstablishment,
jobTitle,
jobQualification,
manager,
occupationCategory,
workingTimeArrangement,
department,
document,
notes
Example:
​
sort
enum<string>[]

Order results by instruction. Read more about sorting. Default: id.

Maximum array length: 100
Available options:
id,
-id,
startsOn,
-startsOn,
endsOn,
-endsOn
Example:
​
lastUpdatedAt
string

Filter out job-positions on their lastUpdatedAt timestamp (range). ISO 8601 formatted date-time-offset-range string. Designed as a right-half-open interval: end is excluded [start, end).

Each bound must be written as yyyy-MM-ddTHH:mm:ss, with optional fractional seconds, followed by an offset (Z or ±hh:mm). Seconds are required. A timestamp read from a response payload can be reused as a bound as is, within a precision of 100 ns.

Examples:

  • 2026-01-01T00:00:00Z--2027-01-01T00:00:00Z: from Jan. 1st 2026 until Dec. 31st 2026.
  • ..--2026-06-01T00:00:00Z: until May 31st 2026 (included).
  • 2026-05-26T00:00:00Z--..: from May 26th 2026.
  • 2026-05-26T07:23:29.7977299+00:00--..: from May 26th 2026, 07:23:29.7977299 UTC.
Pattern: ^(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)|\.\.)--(?:\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)|\.\.)$
Examples:

"2026-01-01T00:00:00Z--2027-01-01T00:00:00Z"

"..--2026-06-01T00:00:00Z"

"2026-05-26T00:00:00Z--.."

"2026-05-26T07:23:29.7977299+00:00--.."

​
page
string

Cursor of the page to retrieve: the page value of links.next.href or links.prev.href in a previous response. Cursors are opaque: don't build or modify them. An invalid cursor gets a 400 Bad Request. Read more about pagination.

​
limit
integer
default:25

Number of items per page. Defaults to 25. Maximum is 1,000. Read more about pagination.

Required range: 0 <= x <= 1000
​
include
enum<string>[]

Include metadata:

  • embedded: the partial or complete representations of related resources (e.g. the employee the resource belongs to).
  • links: links to related resources or actions (e.g. approving a leave-request). May be null when you do not have access to the resource (or action).
  • totalCount: only applicable on collections (i.e. lists of resources), gives the total number of items across all pages.

Read more about expanding responses.

Available options:
embedded,
links,
totalCount

Response

OK

A collection of job-position resources.

​
type
string
Allowed value: "job-positions"
​
url
string<uri>
​
totalCount
integer<int64> | null

Total number of job-position resources across all pages that satisfy query parameters.

Required range: x >= 0
​
items
job-position · object[]

Paginated list of job-position resources.

Maximum array length: 1000
​
links
Links · object | null

Links to related resources

​
embedded
object | null

Embeds the representation of resources related to the job-position(s).

Only returned if requested by the API client: ?include=embedded.