Skip to main content
GET
/
lucca-api
/
job-positions
/
{id}
Retrieve a job-position
curl --request GET \
  --url https://{host}/lucca-api/job-positions/{id} \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'
{
  "id": "74",
  "type": "job-position",
  "url": "https://example.ilucca.net/lucca-api/job-positions/74",
  "remoteId": null,
  "employment": {
    "id": "28",
    "type": "employment",
    "url": "https://example.ilucca.net/lucca-api/employments/28"
  },
  "employee": {
    "id": "416",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/416"
  },
  "startsOn": "2024-01-01",
  "endsOn": null,
  "businessEstablishment": {
    "id": "5",
    "type": "business-establishment",
    "url": "https://example.ilucca.net/lucca-api/business-establishments/5"
  },
  "jobTitle": "Developer",
  "jobQualification": {
    "id": "982",
    "type": "job-qualification",
    "url": "https://example.ilucca.net/lucca-api/job-qualifications/982"
  },
  "manager": {
    "id": "541",
    "type": "employee",
    "url": "https://example.ilucca.net/lucca-api/employees/541"
  },
  "occupationCategory": {
    "id": "12",
    "type": "occupation-category",
    "url": "https://example.ilucca.net/lucca-api/occupation-categories/12"
  },
  "workingTimeArrangement": {
    "id": "23",
    "type": "working-time-arrangement",
    "url": "about:blank"
  },
  "department": {
    "id": "32",
    "type": "department",
    "url": "https://example.ilucca.net/lucca-api/departments/32"
  },
  "document": null,
  "notes": null,
  "updatedAttributes": [
    "jobTitle",
    "jobQualification"
  ],
  "createdAt": "2024-04-15T23:12:54.0001Z",
  "lastUpdatedAt": "2024-04-15T23:12:54.0001Z",
  "links": null,
  "embedded": {
    "department": {
      "32": {
        "id": "32",
        "type": "department",
        "url": "https://example.ilucca.net/lucca-api/departments/32",
        "name": "Finances",
        "remoteId": "FIN",
        "isArchived": false,
        "parent": null,
        "level": 1,
        "manager": {
          "id": "416",
          "type": "employee",
          "url": "https://example.ilucca.net/lucca-api/employees/416"
        },
        "links": {}
      }
    },
    "job-qualification": {
      "982": {
        "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": {}
      }
    },
    "employee": {
      "416": {
        "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": "eatkinson@acme.corp",
        "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"
          }
        }
      }
    },
    "employment": {
      "4561": {
        "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"
        },
        "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"
          }
        }
      }
    }
  }
}
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:
TitleConst
2024-11-01
Examples:

"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.

Examples:

"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.

Examples:

"W/q5sd4w2x1c1gfdg"

Accept-Encoding
string

List of compression algorithms you support.

Path Parameters

id
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.

Read more about expanding responses.

Response

OK

The job position represents a stage in an employee's career during one of their employment in a given business-establishment.

It therefore outlines the attributes of the person as a professional (qualifications) and their role in the company as well as who's their manager. Embedded resources on a job-position(s) response. A job-position resource.

id
string
required
Minimum length: 1
type
string
required
Allowed value: "job-position"
url
string<uri>
required
employment
object
required

Reference to an employment resource.

Examples:
{
"id": "354",
"type": "employment",
"url": "https://example.ilucca.net/lucca-api/employments/354"
}
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
object
required

Reference to a business-establishment resource.

Examples:
{
"id": "5",
"type": "business-establishment",
"url": "https://example.ilucca.net/lucca-api/business-establishments/5"
}
department
object
required

Reference to a department resource. Reference to a department.

Examples:
{
"id": "32",
"type": "department",
"url": "https://example.ilucca.net/lucca-api/departments/32"
}
remoteId
string | null

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

employee
object

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

endsOn
string<date> | null

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
string | null

Short description of the job occupied by this employee.

Maximum length: 250
jobQualification
object | null

Reference to a job-qualification. Reference to a job-qualification resource.

Examples:
{
"id": "982",
"type": "job-qualification",
"url": "https://example.ilucca.net/lucca-api/job-qualifications/982"
}
manager
object | null

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

Examples:
{
"id": "416",
"type": "employee",
"url": "https://example.ilucca.net/lucca-api/employees/416"
}
occupationCategory
object | null

Reference to an occupation-category. Reference to an occupation-category resource.

Examples:
{
"id": "443",
"type": "occupation-category",
"url": "https://example.ilucca.net/lucca-api/occupation-category/443"
}
workingTimeArrangement
object | null

Reference to a working-time-arrangement. Reference to a working-time-arrangement resource.

Examples:
{
"id": "98",
"type": "working-time-arrangement",
"url": "about:blank"
}
document
object | null

Reference to a document resource.

Examples:
{
"id": "95",
"type": "document",
"url": "https://example.ilucca.net/lucca-api/documents/95"
}
notes
string | null

Optional notes about this job-position change.

Maximum length: 500
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.

t9n
object
createdAt
string<date-time-offset>

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

Examples:

"2023-01-23T12:45:23.1234Z"

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.

Examples:

"2023-01-23T12:45:23.1234Z"

embedded
object | null
I