Retrieve a job-position

Security: OAuth 2.0

Scopes:

- job-positions.readonly
- job-positions.readwrite

Business-establishments: This employee's applicable job-position business-establishment.

Working-time arrangements are a beta 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.

Authorizations

Authorization

string

header

required

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

Headers

Api-Version

enum<string>

required

Set the API version.

Available options:

2024-11-01

Allowed value: "2024-11-01"

Maximum string length: 10

If-None-Match

string

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

If-Match

string

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

Accept-Encoding

string

List of compression algorithms you support.

Path Parameters

string

required

Identifier of the job-position to retrieve.

Query Parameters

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.

Response

A job-position resource.

startsOn

string<date>

required

Effective date of this job-position for this employee.

Cannot be outside the range of the employment.

This should be considered "applicable" based on the related employment business-establishment timezone.

businessEstablishment

business-establishment-reference · object

required

Reference to a business-establishment resource.

Show child attributes

businessEstablishment.id

string

required

Minimum string length: 1

businessEstablishment.type

enum<string>

Available options:

business-establishment

Allowed value: "business-establishment"

businessEstablishment.url

string<uri>

department

department-reference · object

required

Reference to a department resource.

Show child attributes

department.id

string

required

Minimum string length: 1

department.type

enum<string>

Available options:

department

Allowed value: "department"

department.url

string<uri>

string

Minimum string length: 1

type

string

Allowed value: "job-position"

url

string<uri>

remoteId

null | string

Resource identifier in a third-party system. No unicity constraint: two job-positions may have the same value.

Required string length: 1 - 1024

employment

employment-reference · object

Reference to an employment resource.

Show child attributes

employment.id

string

required

Minimum string length: 1

employment.type

enum<string>

Available options:

employment

Allowed value: "employment"

employment.url

string<uri>

employee

employee-reference · object

Read-only. Reference to the employment's employee.

Show child attributes

employee.id

string

Minimum string length: 1

employee.type

enum<string>

Available options:

employee

Allowed value: "employee"

employee.url

string<uri>

status

enum<string>

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

endsOn

null | string<date>

Read-only. End date (included) of this job-position effectiveness.

Is calculated from the startsOn property of the closest next job-position, or the endsOn date of the parent employment.

This should be considered "applicable" based on the related employment business-establishment timezone.

Must be greater or equal than StartsOn date.

jobTitle

null | string

Short description of the job occupied by this employee.

Required string length: 1 - 1024

jobQualification

job-qualification-reference · object

Reference to a job-qualification resource.

Show child attributes

jobQualification.id

string

required

Minimum string length: 1

jobQualification.type

enum<string>

Available options:

job-qualification

Allowed value: "job-qualification"

jobQualification.url

string<uri>

manager

employee-reference · object

Reference to another employee, who is considered to be this employee's manager.

Show child attributes

manager.id

string

required

Minimum string length: 1

manager.type

enum<string>

Available options:

employee

Allowed value: "employee"

manager.url

string<uri>

occupationCategory

occupation-category-reference · object

Reference to an occupation-category resource.

Show child attributes

occupationCategory.id

string

required

Minimum string length: 1

occupationCategory.type

enum<string>

Available options:

occupation-category

Allowed value: "occupation-category"

occupationCategory.url

string<uri>

workingTimeArrangement

working-time-arrangement-reference · object

Reference to a working-time-arrangement resource.

Show child attributes

workingTimeArrangement.id

string

required

Minimum string length: 1

workingTimeArrangement.type

enum<string>

Available options:

working-time-arrangement

Allowed value: "working-time-arrangement"

workingTimeArrangement.url

string<uri>

document

document-reference · object

Reference to a document resource.

Show child attributes

document.id

string

required

Minimum string length: 1

document.type

enum<string>

Available options:

document

Allowed value: "document"

document.url

string<uri>

notes

null | string

Optional notes about this job-position change.

Maximum string length: 500

t9n

object

Show child attributes

t9n.jobTitle

Translations · object

Used for translation purposes. Object is structured as a dictionary whose keys refer to translated properties of the parent object, and whose values are a dictionary of supported languages.

On the parent object, the translated property value is considered the "invariant" translation. It is expected to show this value whenever the user's language has no translation in t9n.

Languages are identified through their RFC 4646 language tag.

Show child attributes

t9n.jobTitle.de-DE

string | null

German (Germany)

t9n.jobTitle.en-US

string | null

English (United States of America)

t9n.jobTitle.en-GB

string | null

English (Great Britain)

t9n.jobTitle.es-ES

string | null

Spanish (Spain)

t9n.jobTitle.fr-FR

string | null

French (France)

t9n.jobTitle.fr-CH

string | null

French (Switzerland)

t9n.jobTitle.it-IT

string | null

Italian (Italy)

t9n.jobTitle.nl-BE

string | null

Dutch (Belgium)

t9n.jobTitle.nl-NL

string | null

Dutch (Netherlands)

t9n.jobTitle.pt-PT

string | null

Portuguese (Portugal)

updatedAttributes

enum<string>[]

List of attributes that changed compared with this employee previous job-position, even if said job-position was on another employment and/or not immediately sequential.

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

Available options:

remoteId,

jobTitle,

jobQualification,

occupationCategory,

workingTimeArrangement,

department

createdAt

string<date-time-offset>

Read-only. UTC timestamp of the moment this object was created.

lastUpdatedAt

string<date-time>

Read-only. UTC timestamp of the moment this object was last updated. Set upon creation, update or deletion of the object.

links

object

embedded

object

Show child attributes

embedded.department

object

Dictionary of departments indexed by ID.

Show child attributes

embedded.department.{key}

department · object

A department represents a subdivision of the employee workforce, most often erected around the type of activity they do.

Departments are a tree-like structure, as any department may be child to another.

Note: contrary to most resources, departments are not attached to business-establishments. This means:

business-establishments listed in access rights management do not affect departments.
employees may work in different business-establishments (or even legal-entities) and yet still belong to the same department.

Show child attributes

embedded.department.{key}.name

string

required

Required string length: 1 - 255

embedded.department.{key}.id

string

Minimum string length: 1

embedded.department.{key}.type

string

Allowed value: "department"

embedded.department.{key}.url

string<uri>

embedded.department.{key}.remoteId

null | string

Identifier of this object in a third-party software.

Maximum string length: 255

embedded.department.{key}.isArchived

boolean

If this department is archived. Only possible if there are no more employees attached.

embedded.department.{key}.description

null | string

embedded.department.{key}.parent

department-reference · object

Reference to the department this department is a child of.

Show child attributes

embedded.department.{key}.parent.id

string

required

Minimum string length: 1

embedded.department.{key}.parent.type

enum<string>

Available options:

department

Allowed value: "department"

embedded.department.{key}.parent.url

string<uri>

embedded.department.{key}.level

integer<int32>

Read-only. Depth level of this department in the department tree. At level "1", the department has no parent.

Required range: x >= 1

embedded.department.{key}.manager

employee-reference · object

Reference to the employee that acts as the Head of this department.

Show child attributes

embedded.department.{key}.manager.id

string

required

Minimum string length: 1

embedded.department.{key}.manager.type

enum<string>

Available options:

employee

Allowed value: "employee"

embedded.department.{key}.manager.url

string<uri>

embedded.department.{key}.sortOrder

integer<int32>

Index (0-based) of the department among its siblings.

Required range: x >= 0

embedded.department.{key}.links

object

Show child attributes

embedded.department.{key}.links.activeEmployees

Link · object

Link to the paginated list of active employees currently positioned in this department. List may be partial due to insufficient access rights.

Show child attributes

embedded.department.{key}.links.activeEmployees.href

string<uri>

required

URL to the related object.

Example:

{
  "id": "32",
  "type": "department",
  "url": "https://example.ilucca.net/lucca-api/departments/32",
  "name": "Finances",
  "description": null,
  "remoteId": "FIN",
  "isArchived": false,
  "parent": null,
  "level": 1,
  "manager": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "sortOrder": 2,
  "links": {
    "activeEmployees": {
      "href": "https://example.ilucca.net/lucca-api/employees?applicableJobPosition.department.id=32"
    }
  }
}

embedded.job-qualification

object

Dictionary of job-qualifications indexed by ID.

Show child attributes

embedded.job-qualification.{key}

job-qualification · object

A job-qualification is an object that represents an employee profile regarding their skillset.

It is composed of both:

a profession, which indicates the nature of their job.
a rank (number), which indicates either their level of expertise or of responsibilities in the company.

Show child attributes

embedded.job-qualification.{key}.title

string

required

Must be unique. Invariant name of this job-qualification. Can be translated through t9n.title[{langTag}]. Leading and trailing spaces are automatically removed.

Minimum string length: 1

embedded.job-qualification.{key}.profession

profession-reference · object

required

Reference to a profession resource.

Show child attributes

embedded.job-qualification.{key}.profession.id

string

required

Minimum string length: 1

embedded.job-qualification.{key}.profession.type

enum<string>

Available options:

profession

Allowed value: "profession"

embedded.job-qualification.{key}.profession.url

string<uri>

embedded.job-qualification.{key}.rank

integer<int32>

required

The lower the rank, the "lower" in the company's hierarchy (i.e. the CEO is at max rank). Maximum rank can be set trough configuration.

Required range: x >= 1

embedded.job-qualification.{key}.id

string

Minimum string length: 1

embedded.job-qualification.{key}.type

string

Allowed value: "job-qualification"

embedded.job-qualification.{key}.url

string<uri>

embedded.job-qualification.{key}.t9n

object

Show child attributes

embedded.job-qualification.{key}.t9n.title

Translations · object

Used for translation purposes. Object is structured as a dictionary whose keys refer to translated properties of the parent object, and whose values are a dictionary of supported languages.

On the parent object, the translated property value is considered the "invariant" translation. It is expected to show this value whenever the user's language has no translation in t9n.

Languages are identified through their RFC 4646 language tag.

Show child attributes

embedded.job-qualification.{key}.t9n.title.de-DE

string | null

German (Germany)

embedded.job-qualification.{key}.t9n.title.en-US

string | null

English (United States of America)

embedded.job-qualification.{key}.t9n.title.en-GB

string | null

English (Great Britain)

embedded.job-qualification.{key}.t9n.title.es-ES

string | null

Spanish (Spain)

embedded.job-qualification.{key}.t9n.title.fr-FR

string | null

French (France)

embedded.job-qualification.{key}.t9n.title.fr-CH

string | null

French (Switzerland)

embedded.job-qualification.{key}.t9n.title.it-IT

string | null

Italian (Italy)

embedded.job-qualification.{key}.t9n.title.nl-BE

string | null

Dutch (Belgium)

embedded.job-qualification.{key}.t9n.title.nl-NL

string | null

Dutch (Netherlands)

embedded.job-qualification.{key}.t9n.title.pt-PT

string | null

Portuguese (Portugal)

embedded.job-qualification.{key}.createdAt

string<date-time-offset>

Read-only. UTC timestamp of the moment this object was created.

embedded.job-qualification.{key}.lastUpdatedAt

string<date-time>

Read-only. UTC timestamp of the moment this object was last updated. Set upon creation, update or deletion of the object.

embedded.job-qualification.{key}.links

object

Example:

{
  "id": "982",
  "type": "job-qualification",
  "url": "https://example.ilucca.net/lucca-api/job-qualifications/982",
  "title": "Lead Developer",
  "profession": {
    "id": "89",
    "type": "profession",
    "url": "https://example.ilucca.net/lucca-api/professions/89"
  },
  "rank": 2,
  "createdAt": "2024-04-15T23:12:54.0001Z",
  "lastUpdatedAt": "2024-04-15T23:12:54.0001Z",
  "links": {}
}

embedded.employee

object

Dictionary of employees indexed by ID.

Show child attributes

embedded.employee.{key}

employee · object

The employee represents the public face of an employee in the system. Note that an employee can also represent a trainee, an intern, a contractor, etc...

The applicableEmployment property references the employee's employment that is:

currently in effect if the employee is "active".
will first be in effect if the employee has an employment starting in the future (either the first or a new one).
was last in effect if the employee is no longer employed and is not expected to be re-remployed in the future.

The applicableJobPosition property references the employee's job-position that matches the same logic.

Show child attributes

embedded.employee.{key}.givenName

string

required

Name given at birth. In the U.S.A., the first name of a person. In French: "prénom". Leading and trailing spaces are automatically removed.

Required string length: 1 - 255

embedded.employee.{key}.familyName

string

required

Name inherited from the person's family. In the U.S.A., the last name of a person. In French: "nom (de famille)". Leading and trailing spaces are automatically removed.

Required string length: 1 - 255

embedded.employee.{key}.email

null | string<email>

required

Professional email of this employee. "<" and ">" characters are forbidden. Some domains are blacklisted and may thus result in 400 errors.

Required string length: 3 - 255

embedded.employee.{key}.id

string

Minimum string length: 1

embedded.employee.{key}.type

string

Allowed value: "employee"

embedded.employee.{key}.url

string<uri>

embedded.employee.{key}.remoteId

null | string

Must be unique.

Required string length: 1 - 100

embedded.employee.{key}.portrait

portrait-reference · object

Reference to the employee's portrait, which is a file (picture) representing them.

Show child attributes

embedded.employee.{key}.portrait.id

string

required

Minimum string length: 1

embedded.employee.{key}.portrait.type

string

Allowed value: "portrait"

embedded.employee.{key}.portrait.url

string<uri>

embedded.employee.{key}.employeeNumber

null | string

Required string length: 1 - 50

embedded.employee.{key}.status

enum<string>

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

embedded.employee.{key}.birthDay

object

Year-less date of birth.

Read-only, as it is infered from the employee-personal-record birthDate. Take note that month starts at "1" and not zero, i.e. "1" is for January, "2" for February, etc...

Show child attributes

embedded.employee.{key}.birthDay.day

integer<int32>

required

Starts at "1". Maximum depends on the month.

Required range: 1 <= x <= 31

embedded.employee.{key}.birthDay.month

integer<int32>

required

Starts at "1" and goes up to "12" (included).

Required range: 1 <= x <= 12

embedded.employee.{key}.phoneNumber

string<phone> | null

Professional phone number of this employee.

Example:

"+3356565656"

embedded.employee.{key}.applicableEmployment

object

Read-only. Reference to the applicable employment of this employee. If the employee status is "deactivated", then references their last employment. If the employee status is "upcoming", then references their closest next employment.

Show child attributes

embedded.employee.{key}.applicableEmployment.id

string

Minimum string length: 1

embedded.employee.{key}.applicableEmployment.type

string

Allowed value: "employment"

embedded.employee.{key}.applicableEmployment.url

string<uri>

embedded.employee.{key}.applicableJobPosition

object

Read-only. Reference to the active job-position of this employee. Matches the same logic as the "applicableEmployment".

Show child attributes

embedded.employee.{key}.applicableJobPosition.id

string

Minimum string length: 1

embedded.employee.{key}.applicableJobPosition.type

string

Allowed value: "job-position"

embedded.employee.{key}.applicableJobPosition.url

string<uri>

embedded.employee.{key}.createdAt

string<date-time-offset>

Read-only. UTC timestamp of the moment this object was created.

embedded.employee.{key}.lastUpdatedAt

string<date-time>

Read-only. UTC timestamp of the moment this object was last updated. Set upon creation, update or deletion of the object.

embedded.employee.{key}.links

object

Show child attributes

embedded.employee.{key}.links.employments

Link · object

Object that represents an hyperlink.

Show child attributes

embedded.employee.{key}.links.employments.href

string<uri>

required

URL to the related object.

embedded.employee.{key}.links.jobPositions

Link · object

Object that represents an hyperlink.

Show child attributes

embedded.employee.{key}.links.jobPositions.href

string<uri>

required

URL to the related object.

embedded.employee.{key}.links.personalRecord

Link · object

Object that represents an hyperlink.

Show child attributes

embedded.employee.{key}.links.personalRecord.href

string<uri>

required

URL to the related object.

Example:

{
  "id": "416",
  "type": "employee",
  "url": "https://example.ilucca.net/lucca-api/employees/416",
  "remoteId": "00002345",
  "portrait": {
    "id": "66512232",
    "type": "portrait",
    "url": "https://example.ilucca.net/lucca-api/portraits/66512232"
  },
  "givenName": "Edward",
  "familyName": "Atkinson",
  "employeeNumber": "E000124",
  "status": "active",
  "email": "[email protected]",
  "birthDay": { "day": 22, "month": 12 },
  "phoneNumber": "+33145784512",
  "applicableEmployment": {
    "id": "154",
    "type": "employment",
    "url": "https://example.ilucca.net/lucca-api/employments/154"
  },
  "applicableJobPosition": {
    "id": "74",
    "type": "job-position",
    "url": "https://example.ilucca.net/lucca-api/job-positions/74"
  },
  "createdAt": "2024-04-15T23:12:54.0001Z",
  "lastUpdatedAt": "2024-04-15T23:12:54.0001Z",
  "links": {
    "employments": {
      "href": "https://example.ilucca.net/lucca-api/employments?employee.id=416"
    },
    "jobPositions": {
      "href": "https://example.ilucca.net/lucca-api/job-positions?employment.employee.id=416"
    },
    "personalRecord": {
      "href": "https://example.ilucca.net/lucca-api/employee-personal-records?employee.id=416"
    }
  }
}

embedded.employment

object

Dictionary of employment indexed by ID.

Show child attributes

embedded.employment.{key}

employment · object

The employment resource represents a relationship between an employee and a legal-entity over a continuous period. It may actually represent a work contract, an internship agreement, a contractor's contract, etc...

The actual job of the employee is defined through the job-position resource, which references an employment. Over the course of his/her employment, the employee may occupy several job-positions.

Show child attributes

embedded.employment.{key}.legalEntity

Reference to a legal-entity · object

required

Read-only. Reference to a legal-entity. Inferred from the business-establishment of its first job-position.

Show child attributes

embedded.employment.{key}.legalEntity.id

string

required

Minimum string length: 1

embedded.employment.{key}.legalEntity.type

enum<string>

Available options:

legal-entity

Allowed value: "legal-entity"

embedded.employment.{key}.legalEntity.url

string<uri>

embedded.employment.{key}.start

object

required

Show child attributes

embedded.employment.{key}.start.date

string<date>

required

Date of the first day (included) of this employment.

embedded.employment.{key}.template

employment-template-reference · object

required

Reference to an employment-template resource.

Show child attributes

embedded.employment.{key}.template.id

string

required

Minimum string length: 1

embedded.employment.{key}.template.type

enum<string>

Available options:

employment-template

Allowed value: "employment-template"

embedded.employment.{key}.template.url

string<uri>

embedded.employment.{key}.id

string

Minimum string length: 1

embedded.employment.{key}.type

string

Allowed value: "employment"

embedded.employment.{key}.url

string<uri>

embedded.employment.{key}.remoteId

null | string

Resource identifier in a third-party system.

Required string length: 1 - 200

embedded.employment.{key}.employee

employee-reference · object

Reference to an employee resource.

Show child attributes

embedded.employment.{key}.employee.id

string

required

Minimum string length: 1

embedded.employment.{key}.employee.type

enum<string>

Available options:

employee

Allowed value: "employee"

embedded.employment.{key}.employee.url

string<uri>

embedded.employment.{key}.status

enum<string>

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

embedded.employment.{key}.end

object

Show child attributes

embedded.employment.{key}.end.date

string<date>

required

Date of the last day (included) of this employment. After this date, this employment is considered terminated.

Leave null for permanent employments (as long as the employee is kept), and set the date of the last day in case of a fixed-term employment.

EndsOn date must be greater or equal than StartsOn date.

embedded.employment.{key}.document

file-reference · object

Reference to a file resource.

Show child attributes

embedded.employment.{key}.document.id

string

required

Minimum string length: 1

embedded.employment.{key}.document.type

enum<string>

Available options:

file

Allowed value: "file"

embedded.employment.{key}.document.url

string<uri>

Example:

{
  "id": "9283sdf",
  "type": "file",
  "url": "https://example.ilucca.net/lucca-api/files/9283sdf"
}

embedded.employment.{key}.createdAt

string<date-time-offset>

Read-only. UTC timestamp of the moment this object was created.

embedded.employment.{key}.lastUpdatedAt

string<date-time>

Read-only. UTC timestamp of the moment this object was last updated. Set upon creation, update or deletion of the object.

embedded.employment.{key}.links

object

Show child attributes

embedded.employment.{key}.links.jobPositions

Link · object

Link to the related job-positions for this employment.

Show child attributes

embedded.employment.{key}.links.jobPositions.href

string<uri>

required

URL to the related object.

embedded.employment.{key}.links.probationaryPeriods

Link · object

Link to the related probationary-periods for this employment.

Show child attributes

embedded.employment.{key}.links.probationaryPeriods.href

string<uri>

required

URL to the related object.

Example:

{
  "id": "4561",
  "type": "employment",
  "url": "https://example.ilucca.net/lucca-api/employments/4561",
  "remoteId": "EMPLOYMENT#4512-ac",
  "employee": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "legalEntity": {
    "id": "123",
    "type": "legal-entity",
    "url": "https://example.ilucca.net/lucca-api/legal-entities/123"
  },
  "status": "active",
  "start": { "date": "2024-01-01" },
  "end": null,
  "document": {
    "id": "74411",
    "type": "file",
    "url": "https://example.ilucca.net/lucca-api/files/74411"
  },
  "template": {
    "id": "4",
    "type": "employment-template",
    "url": "https://example.ilucca.net/lucca-api/employment-templates/4"
  },
  "createdAt": "2024-04-15T23:12:54.0001Z",
  "lastUpdatedAt": "2024-04-15T23:12:54.0001Z",
  "links": {
    "jobPositions": {
      "href": "https://example.ilucca.net/lucca-api/job-positions?employment.id=4561"
    },
    "probationaryPeriods": {
      "href": "https://example.ilucca.net/lucca-api/probationary-periods?employment.id=4561"
    }
  }
}

Overview

Organization

Employee Records

Events & Webhooks

Retrieve a job-position

Authorizations

Headers

Path Parameters

Query Parameters

Response