Employees API¶

URL¶

POST /api/v1/employees/

Settings¶

The POST is in JSON (Content-Type: application/json): It contains the employee’s attributes:

• lastname: VARCHAR(70) / mandatory

  Last name of the employee

• firstname: VARCHAR(30) / mandatory

  First name

• maiden_name: VARCHAR(70) / optional

  Maiden name

• email: VARCHAR(80) / optional or mandatory

  Professional e-mail of the employee. Used to send personal vault activation codes to employees. If empty, the invitation is sent via conventional mail containing the vault activation code (project).

• technical_id: VARCHAR(50) / mandatory

  Technical identifier corresponding to the unique identifier of the employee in the HRIS of the Client. It is recommended to specify a unique employee identifier if such an identifier exists in the HRIS. This identifier (generally) is not the employee number. But if it is guaranted that the employee number is unique, even in the event of a transfer, or in the event of a departure and reassignment, the employee number may then be used as this identifier.

• registration_references: List of employee numbers and organizations associated with the employee. These organizations and employee numbers are added to the employee if they are not already present. No employee number is deleted in this call: in particular, in case of an employee update, even if this parameter ‘registration_references’ is an empty list, the existing employee numbers aren’t deleted:

  • organization_code: VARCHAR(64) / mandatory

    Code of the organization with which the employee number is associated

  • registration_number: VARCHAR(255) / mandatory

    Employee number within the organization. The pair registration number and organization code should be unique

  • active: [true, false] / optional, default: true

    Status of the employee number

  • departure_date: YYYY-MM-DD / optional, default: today

    Employee’s departure date from the organization in ISO format``YYYY-MM-DD``. If not provided, the current date is used

• dob: YYYY-MM-DD / optional

  Employee birth date in ISO format``YYYY-MM-DD``. Deduplication checks are performed based on this field, it is therefore advisable to fill it in

• address1: VARCHAR(255) / optional or mandatory

  Employee address, in the “no. and street” format. This field is mandatory if the e-mail field is not filled in

• address2: VARCHAR(255) / optional

  Additional address (Floor, Stairwell, Apartment…)

• address3: VARCHAR(255) / optional

  Additional address fields (Residence, Housing Development, Building, Apartment Building, Subdivision, etc.)

• zip_code: VARCHAR(30) / optional or mandatory

  Postal code. This field is mandatory if the e-mail field is not filled in

• city: VARCHAR(100) / optional or mandatory

  City in which the employee resides. This field is mandatory if the e-mail field is not filled in

• country: VARCHAR(2) / optional or mandatory

  ISO country code (FR, EN, ES…). This field is mandatory if the e-mail field is not filled in. For a list of valid country codes see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3

• phone_number: VARCHAR(50) / optional

  Employee phone number. Format using International prefix format; eg: ``00116434774000``.

• mobile_phone_number: VARCHAR(50) / optional

  Mobile phone number. Format using International prefix format; eg: ``0116434774000``. This number is the one used by default when notifying the employee to sign a document or to confirm his identity. If not filled then the phone number is used

• electronic_payslips_opted_out: true/false / optional

  For European based clients only, did the Employee ask to opt out from receiving their payslips digitally (true)? Or on the contrary, did they agree to receive them digitally (false)? If the employee did not communicate any choice, false is returned. Changing this value also sets the value of electronic_payslips_opted_out_date to today’s date.

• disable_elec_distribution: true/false / optional

  Prevent electronic documents to be sent to the employee’s vault

• disable_paper_distribution: true/false / optional

  Prevent paper documents to be sent to the employee

• starting_date: YYYY-MM-DD / optional

  Starting date of the employee in your company in the ISO format``YYYY-MM-DD``

• gone: true/false / optional

  Flag to mark the employee as terminated. By default: false. If true all registration numbers are set to inactive

• disable_vault: true/false / optional

  Disable/enable employee’s vault. If it is not provided, or if the employee’s vault is already activated, it is ignored and set to false by default

• filters: optional

  Dictionary of employee custom fields.

  Example::

  {
      'nh': '4',
      'title': 'director'
  }
  

{
  'lastname': 'MARTIN',
  'firstname': 'Paul',
  'email': 'mpaul@example.com',
  'technical_id': 'internal056',
  'registration_references': [
    {
      'organization_code': 'FSUD1',
      'registration_number': 'BYUIE5685678',
      'active': 'true'
    },
    {
      'organization_code': 'FSUD2',
      'registration_number': 'BYUIE5685677',
      'active': 'false',
      'departure_date': '2014-12-31'
    }
  ]
  'dob': '1985-04-12',
  'address1': '34 rue du général',
  'zip_code': '75016',
  'city': 'Paris',
  'country': 'FR',
  'mobile_phone_number': '0033645764425',
  'electronic_payslips_opted_out': true,
  'filters': {
      'nh': '4',
      'title': 'director'
  }
}

Response¶

HTTP 400 Bad Request
{
  'errors': [
    {
      'code': 1400,
      'msg': 'Family name is required'
    },
    {
      'code': 1409,
      'msg': 'This firstname, lastname and registration ref are arlready used for this domain'
    }
  ]
}

curl -v -X POST "https://api.novapost.net/api/v1/employees/" \
    -H "Content-type: application/json" \
    -H "Accept: application/json" \
    -H "X-API-KEY: toto" \
    -d "{\"lastname\": \"TAPTAP9\", \"firstname\": \"gregory9\", \"email\": \"gregory9@example.com\", \"technical_id\": \"testgregory9\", \"registration_references\": [{\"organization_code\": \"AP\", \"registration_number\": \"testgregory9\", \"active\": \"true\"}],\"dob\": \"1985-04-12\",\"address1\": \"34 rue du général\", \"zip_code\": \"75016\", \"city\": \"Paris\", \"country\": \"FR\", \"mobile_phone_number\": \"0033645764425\"}"

URL¶

GET /api/v1/employees/{technical_id}/

Settings¶

GET parameters:

• technical_id: VARCHAR(50) / optional or mandatory

  Internal employee identifier within the HRIS and reported during the employee creation on UKG HR Service Delivery

• electronic_payslips_opt_out_origin: VARCHAR(50) / optional

  If the employee is reported as opted out from the electronic payslip, describe if the decision was made by the employee or by the enterprise (default). Otherwise null

• electronic_payslips_opt_out_date: YYYY-MM-DD / optional

  Date when the choice of the employee to opt out was recorded

Response¶

URL¶

POST /api/v1/employees/{technical_id}/registrations/

Settings¶

GET parameters:

• technical_id: VARCHAR(50) / optional or mandatory

  Internal employee identifier within the HRIS and reported during the employee creation on UKG HR Service Delivery

The POST is encoded in JSON (Content-Type: application/json) and contains the following parameters:

• organization_code: VARCHAR(64) / mandatory

  Code of the organization with which the employee number is associated

• registration_number: VARCHAR(255) / mandatory

  Employee number within the organization ‘organization_code’

• active: [true, false] / optional, default: true

  Status of this employee number.

• departure_date: YYYY-MM-DD / optional, default: today

  Date of employee’s departure in ISO format``YYYY-MM-DD``, if the employee number is not active. If not provided, the current date is registered.

{
  'registration_number': '4564564464FFS',
  'organization_code': 'FSUD1',
  'active': 'true'
}

Response¶

HTTP 400 Bad Request
{
  'errors': [
    {
        'code': 1400,
        'msg': 'Org code is required'
    },
   ...
  ]
}

URL¶

DELETE /api/v1/employees/{technical_id}/registrations/{organization_code}/{registration_number}/

Settings¶

GET parameters:

• technical_id: VARCHAR(50) / optional or mandatory

  Internal employee identifier within the HRIS and reported during the employee creation on UKG HR Service Delivery

• organization_code: VARCHAR(64) / mandatory

  Code of the organization with which the employee number is associated

• registration_number: VARCHAR(255) / mandatory

  Employee number within the organization ‘organization_code’

Response¶

URL¶

PUT /api/v1/employees/{technical_id}/gone/

Settings¶

GET parameters:

• technical_id: VARCHAR(50) / optional or mandatory

  Internal employee identifier within the HRIS and reported during the employee creation on UKG HR Service Delivery

Response¶

URL¶

PUT /api/v1/employees/{technical_id}/back/

Settings¶

GET parameters:

• technical_id: VARCHAR(50) / optional or mandatory

  Internal employee identifier within the HRIS and reported during the employee creation on UKG HR Service Delivery

Response¶