List employee-personal-records

GET

lucca-api

employee-personal-records

curl --request GET \
  --url https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com/lucca-api/employee-personal-records \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'

{
  "type": "employee-personal-records",
  "url": "https://example.ilucca.net/lucca-api/employee-personal-records?page=qsdkuh&limit=1",
  "items": [
    {
      "id": "897",
      "type": "employee-personal-record",
      "url": "https://example.ilucca.net/lucca-api/employee-personal-records/897",
      "employee": {
        "id": "416",
        "type": "employee",
        "url": "https://example.ilucca.net/lucca-api/employees/416"
      },
      "title": "mister",
      "legalGender": "male",
      "birthDate": "1989-12-21",
      "insuranceNumber": {
        "format": "frenchSSN",
        "value": "1760774865895 37"
      },
      "nationalitiesCountryCodes": [
        "FRA"
      ],
      "bankAccount": {
        "format": "iban",
        "iban": "FR8817569000503595615775H03",
        "bic": "PSSTFRPPXXX"
      },
      "phoneNumber": "+33456789634",
      "email": "jdoe13@gmail.com",
      "links": null
    }
  ],
  "totalCount": 203,
  "embedded": {
    "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"
          }
        }
      }
    }
  },
  "links": {
    "prev": null,
    "next": {
      "href": "https://example.ilucca.net/lucca-api/{resource-type}?page=!sdk87Sdh&limit=25"
    }
  }
}

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

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

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

200

application/json

An collection of employee-personal-record resources.

type

string

required

Allowed value: "employee-personal-records"

url

string

required

items

object[]

required

The employee-personal-record resource represents the confidential attributes of an employee, i.e. sensitive personal information about them which gives details of their background, identity proofs, and qualifications.

items.id

string

required

Minimum length: 1

items.type

string

required

Allowed value: "employee-personal-record"

items.url

string

required

items.employee

object

required

Only one employee-personal-record per employee.

Example:

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

items.title

enum<string>

unknown: Not indicated. Equivalent to a technical null.
mister: Either married or unmarried man. French: 'Monsieur'.
miss: Unmarried woman. French: 'Mademoiselle'.
misses: Married woman. French: 'Madame'.
mizz: Either married or unmarried woman. No French equivalent.

Available options:

unknown,

mister,

miss,

misses,

mizz,

doctor,

professor,

master

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

Example:

"unknown"

items.birthDate

string | null

YYYY-MM-DD formatted date of birth.

items.insuranceNumber

object | null

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

items.nationalitiesCountryCodes

enum<string>[]

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

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

items.bankAccount

object | null

Represents a bank-account. Several formats are supported.

Example:

{
  "format": "iban",
  "iban": "FR7630006000011234567890189",
  "bic": null
}

items.phoneNumber

string

Phone number.

Example:

"+3356565656"

items.email

string | null

Personal email address of the employee.

items.links

null

totalCount

integer | null

Total number of employee-personal-record resources across all pages that satisfy query parameters.

Required range: x >= 0

embedded

object | null

embedded.employee

object | null

Dictionary of employees indexed by ID.

embedded.employee.{key}

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.

embedded.employee.{key}.id

string

required

Minimum length: 1

embedded.employee.{key}.type

string

required

Allowed value: "employee"

embedded.employee.{key}.url

string

required

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 - 100

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 - 100

embedded.employee.{key}.email

string | null

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

string | null

Must be unique.

Required string length: 1 - 100

embedded.employee.{key}.portrait

object | null

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

Example:

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

embedded.employee.{key}.employeeNumber

string | null

Minimum length: 1

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

Example:

"active"

embedded.employee.{key}.birthDay

object | null

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

embedded.employee.{key}.phoneNumber

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

embedded.employee.{key}.applicableJobPosition

object

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

embedded.employee.{key}.createdAt

string

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

Example:

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

embedded.employee.{key}.lastUpdatedAt

string

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

Example:

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

embedded.employee.{key}.links

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

links

object | null

Links to related resources

Was this page helpful?

The employee-personal-record resource

Retrieve an employee-personal-record

curl --request GET \
  --url https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com/lucca-api/employee-personal-records \
  --header 'Api-Version: <api-version>' \
  --header 'Authorization: Bearer <token>'

{
  "type": "employee-personal-records",
  "url": "https://example.ilucca.net/lucca-api/employee-personal-records?page=qsdkuh&limit=1",
  "items": [
    {
      "id": "897",
      "type": "employee-personal-record",
      "url": "https://example.ilucca.net/lucca-api/employee-personal-records/897",
      "employee": {
        "id": "416",
        "type": "employee",
        "url": "https://example.ilucca.net/lucca-api/employees/416"
      },
      "title": "mister",
      "legalGender": "male",
      "birthDate": "1989-12-21",
      "insuranceNumber": {
        "format": "frenchSSN",
        "value": "1760774865895 37"
      },
      "nationalitiesCountryCodes": [
        "FRA"
      ],
      "bankAccount": {
        "format": "iban",
        "iban": "FR8817569000503595615775H03",
        "bic": "PSSTFRPPXXX"
      },
      "phoneNumber": "+33456789634",
      "email": "jdoe13@gmail.com",
      "links": null
    }
  ],
  "totalCount": 203,
  "embedded": {
    "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"
          }
        }
      }
    }
  },
  "links": {
    "prev": null,
    "next": {
      "href": "https://example.ilucca.net/lucca-api/{resource-type}?page=!sdk87Sdh&limit=25"
    }
  }
}

Overview

Organization

Employee Records

List employee-personal-records

Authorizations

Headers

Query Parameters

Response