Retrieve an employee-personal-record

Security: OAuth 2.0

Scopes:

- employee-personal-records.readonly
- employee-personal-records.readwrite

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

About authentication

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 employee-personal-record 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

An employee-personal-record resource.

string

Minimum string length: 1

type

string

Allowed value: "employee-personal-record"

url

string<uri>

employee

employee-reference · object

Read-only. Reference to an employee resource.

Show child attributes

employee.id

string

Minimum string length: 1

employee.type

enum<string>

Available options:

employee

Allowed value: "employee"

employee.url

string<uri>

title

enum<string>

default:unknown

unknown: Not indicated. Equivalent to a technical null.
mister: Either married or unmarried man. French: 'Monsieur'.
miss: Unmarried woman. French: 'Mademoiselle'.

Available options:

unknown,

mister,

miss

legalGender

enum<string>

default:unknown

"Unknown" is equivalent to "unspecified" or "null".

"Diverse" may be legally acknowledged in some countries (e.g. Germany).

Available options:

unknown,

male,

female,

diverse

birthDate

null | string<date>

insuranceNumber

insurance-number · object

Validation depends on selected format. Value for "other" format is not validated.

Show child attributes

insuranceNumber.format

enum<string>

Available options:

frenchSSN,

swissSSN,

other

insuranceNumber.value

string

nationalitiesCountryCodes

enum<string>[]

Array of ISO 3166-1 alpha-3 country codes.

Maximum array length: 1

Three letters ISO 3166-1 alpha-3 country code.

Available options:

FRA,

ESP,

DEU,

CHE,

ITA,

GBR,

USA,

BEL,

CAN,

AFG,

ALA,

ALB,

DZA,

ASM,

AND,

AGO,

AIA,

ATA,

ATG,

ARG,

ARM,

ABW,

AUS,

AUT,

AZE,

BHS,

BHR,

BGD,

BRB,

BLR,

BLZ,

BEN,

BMU,

BTN,

BOL,

BIH,

BWA,

BVT,

BRA,

VGB,

IOT,

BRN,

BGR,

BFA,

BDI,

KHM,

CMR,

CPV,

CYM,

CAF,

TCD,

CHL,

CHN,

HKG,

MAC,

CXR,

CCK,

COL,

COM,

COG,

COD,

COK,

CRI,

CIV,

HRV,

CUB,

CYP,

CZE,

DNK,

DJI,

DMA,

DOM,

ECU,

EGY,

SLV,

GNQ,

ERI,

EST,

ETH,

FLK,

FRO,

FJI,

FIN,

GUF,

PYF,

ATF,

GAB,

GMB,

GEO,

GHA,

GIB,

GRC,

GRL,

GRD,

GLP,

GUM,

GTM,

GGY,

GIN,

GNB,

GUY,

HTI,

HMD,

VAT,

HND,

HUN,

ISL,

IND,

IDN,

IRN,

IRQ,

IRL,

IMN,

ISR,

JAM,

JPN,

JEY,

JOR,

KAZ,

KEN,

KIR,

PRK,

KOR,

KWT,

KGZ,

LAO,

LVA,

LBN,

LSO,

LBR,

LBY,

LIE,

LTU,

LUX,

MKD,

MDG,

MWI,

MYS,

MDV,

MLI,

MLT,

MHL,

MTQ,

MRT,

MUS,

MYT,

MEX,

FSM,

MDA,

MCO,

MNG,

MNE,

MSR,

MAR,

MOZ,

MMR,

NAM,

NRU,

NPL,

NLD,

NCL,

NZL,

NIC,

NER,

NGA,

NIU,

NFK,

MNP,

NOR,

OMN,

PAK,

PLW,

PSE,

PAN,

PNG,

PRY,

PER,

PHL,

PCN,

POL,

PRT,

PRI,

QAT,

REU,

ROU,

RUS,

RWA,

BLM,

SHN,

KNA,

LCA,

MAF,

SXM,

SPM,

VCT,

WSM,

SMR,

STP,

SAU,

SEN,

SRB,

SYC,

SLE,

SGP,

SVK,

SVN,

SLB,

SOM,

ZAF,

SGS,

SSD,

LKA,

SDN,

SUR,

SJM,

SWZ,

SWE,

SYR,

TWN,

TJK,

TZA,

THA,

TLS,

TGO,

TKL,

TON,

TTO,

TUN,

TUR,

TKM,

TCA,

TUV,

UGA,

UKR,

ARE,

UMI,

URY,

UZB,

VUT,

VEN,

VNM,

VIR,

WLF,

ESH,

YEM,

ZMB,

ZWE

Required string length: 3

bankAccount

object

Represents a bank account in any format, including IBAN, SWIFT, and region-specific routing details.

Show child attributes

bankAccount.format

enum<string>

default:other

required

Available options:

other,

iban

bankAccount.bankName

null | string

Optional name of the bank.

Required string length: 1 - 255

bankAccount.accountIdentifier

null | string

When format is iban, then an IBAN is expected. Otherwise, may be any local / domestic bank account number.

Required string length: 1 - 255

bankAccount.bankIdentifier

null | string

When format is iban, then null is expected, given that an IBAN already identifies the bank establishment. Otherwise, may be any local bank identifier / routing number or international SWIFT BIC code.

Required string length: 1 - 255

Example:

{
  "format": "iban",
  "bankName": "BNP Paribas",
  "accountIdentifier": "FR7630006000011234567890189",
  "bankIdentifier": null
}

phoneNumber

string<phone> | null

Phone number.

Example:

"+3356565656"

null | string<email>

Personal email address of the employee.

Required string length: 3 - 255

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

Overview

Organization

Employee Records

Events & Webhooks

Retrieve an employee-personal-record

Authorizations

Headers

Path Parameters

Query Parameters

Response