Requests API

Overview

A request in UKG HR Service Delivery includes the following main attributes:

  • An employee (the creator of the request, or the employee concerned by this request)

  • A creator (the employee, or a manager or HR staff user that post the request on behalf of the employee)

  • The response values corresponding to a particular form. Each form is defined and build on the administration in the administration panel and include a number of fields (Date fields, text fields,…)

Create a request

This method creates a new request for a form and an employee

URL

POST /api/requests/
    Accept: application/json
    Content-Type: multipart/form-data"
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Parameters

The POST is in multipart/form-data” (Content-Type: multipart/form-data"):

Parameter

Description

Type

mandatory

Exemple

employee_technical_id

Technical employee identifier in UKG HR Service Delivery.

VARCHAR(50)

optional

employee_technical_id: XAQ678900

creator_technical_id

Technical manager identifier in UKG HR Service Delivery.

VARCHAR(50)

mandatory

creator_technical_id: Y78GHYU

subject

Subject of the request

VARCHAR(256)

optionnal or required required on default form

subject: Vacances

body

Body of the request

VARCHAR

optionnal or required required on default form

body: Voici ma demande…

origin

The origin of the request

ENUM(PHONE, EMAIL, PEOPLASK)

optional defaults to API

origin: EMAIL

priority

Priority of the request, default to NORMAL

ENUM(LOW, NORMAL, URGENT)

optional

priority: LOW

visible_to_employee

If true, this request will be displayed on the employee portal on the dashboard and email notifications will be sent to the employee. If false, this request is only visible for the assigned managers and email notifications will only be sent to them.

BOOLEAN

optional defaults to false

visible_to_employee: true

processing_date_due

Due date of this request (can be calculated / overridden by a automatic processing rule after this call)

DATE

optional

processing_date_due: 2012-01-01T12:00:00+00:00

callback_url

Callback URL used to notify the client application

URL (VARCHAR)

optional

callback_url: https://clientapp.com/request-event/

form_code

Code of the form

VARCHAR

mandatory

form_code: “my-form-slug”

form_field_code_1

Code of the first field of the form referenced by the form_code parameter.

VARCHAR(20)

optionnal or required depending on the form schema

start_vacation_date: 2012-01-01T12:00:00+00:00

form_field_code_n

Code of the last field of the form referenced by the form_code parameter.

VARCHAR(20)

optionnal or required depending on the form schema

comment: Bonjour,\nDemande de vacance pour février\nMerci!\nCdt

form_field_file_code_1

Code of the first file field of the form referenced by the form_code parameter.

BINARY

optional or required depending on the form schema

file_employee_vacation_status: <any_binary_file>

file_form_field_file_code_n

Code of the last file field of the form referenced by the form_code parameter.

BINARY

optional or required depending on the form schema

file_manager_confirmation: <any_binary_file>

Response

Success

The response is encoded in the JSON format with the following parameters:

Parameter

Description

Type

Exemple

id

The id of the request

INTEGER

789

form

Code of the form

OBJECT

{…}

subject

Subject of the request (can be set by the creator of the request or automatically generated depending on the form)

VARCHAR(256)

What’s the company vacation policy?

body

Request body (html)

TEXT

… long body ….

body_json

Request body (json), if the form is a custom form

JSON

origin

Origin (can be set by the creator of the request if the request is pmade by a manager)

ENUM(PEOPLASK,EMAIL,PHONE,API)

PEOPLASK

status

State of the request

ENUM(created,open,pending,closed)

created

custom_state

Custom state of the request (possibly set in the processing rules)

VARCHAR(100)

Manager validation pending

employee

Employee related to this request

OBJECT

{…}

creator

Creator of this request (can be the employee himself, or a manager)

OBJECT

{…}

managers_assigned

List of managers assigned to this request (at the time of the API call)

LIST

[{…},{…},…]

processing_date_due

Due date of this request (can be calculated / overridden by a automatic processing rule)

DATETIME

2012-01-01T12:00:00+00:00

processing_start_date

Processing start date of this request (can be calculated / overridden by a automatic processing rule)

DATETIME

2012-01-01T12:00:00+00:00

created_at

Creation date of this request (date of the api call)

DATETIME

2012-01-01T12:00:00+00:00

updated_at

Last update of the request

DATETIME

2012-01-01T12:00:00+00:00

closed_by

The manager who closed the request if the request is closed and if known. If it has been reopened, then closed again, the last manager who closed the request is returned.

OBJECT

{…}

closed_at

Last date the request has been closed

DATETIME

2012-01-01T12:00:00+00:00

manager_url

The URL of the request in Request Manager (needs manager authentication)

URL

https://xxxx.peopleask.com/

employee_url

The URL of the request in Request Manager employee portal (needs employee authentication)

URL

https://xxxx.peopleask.com/

api_url

The URI of the request (needs API authentication)

URL

https://xxxx.peopleask.com/

visible_by_employee

Indicates if the request is visible by employees

BOOLEAN

true

HTTP 200 OK:

HTTP/1.1 200 OK
{
  "id": "678",
  "form": {
    "slug": "onboarding-form",
    "title": "Welcome!!",
    "category": {
        "slug": "onboarding",
        "name": "OnBoarding Section!",
        "language_code": "en",
        "description": "..."
    },
    "featured": false,
    "total_hits": 5678,
    "updated_at": "2012-01-01T12:00:00+00:00",
    "created_at": "2012-01-01T12:00:00+00:00",
    "api_url": "https://API_DOMAIN/api/forms/:slug/",
   }
  "subject": "Ticket subject",
  "body": "<div>...</div>",
  "body_json": {
    "start_vacation_date": "2012-01-01T12:00:00+00:00",
    "comment": "Thank you for validating this request \n Regards",
    "file_employee_vacation_status": "/ticket/requests/567/file/56789/"
  },
  "origin": "PEOPLASK",
  "status": "closed",
  "custom_state": "",
  "category": "Vacancies",
  "employee": {
    "technical_id": "NT7896789",
    "first_name": "Bill",
    "last_name": "Riveman",
    "email": "employee333@example.com"
  },
  "creator": {
    "technical_id": "H86789678",
    "first_name": "Jonh",
    "last_name": "Steinberg",
    "email": "manager78990@example.com"
  },
  "managers_assigned": [
    {
      "technical_id": "KLU907",
      "first_name": "Natalie",
      "last_name": "Steinberg",
      "email": "manager7grt0@example.com"
    },
    {
      "technical_id": "HG789Y79",
      "first_name": "Manuel",
      "last_name": "Bisho",
      "email": "manager7530@example.com"
    }
  ],
  "processing_date_due": "2012-01-01T12:00:00+00:00",
  "processing_start_date": "2012-01-01T12:00:00+00:00",
  "created_at": "2012-01-01T12:00:00+00:00",
  "updated_at": "2012-01-01T12:00:00+00:00",
  "closed_by": {
    "technical_id": "KLU907",
    "first_name": "Natalie",
    "last_name": "Steinberg",
    "email": "manager7grt0@example.com"
  },
  "closed_at": "2012-01-01T12:00:00+00:00",
  "api_url": "https://API_DOMAIN/api/request/18/",
  "manager_url": "https://CLIENT-SUBDOMAIN/manager/request/18/",
  "employee_url": "https://CLIENT-SUBDOMAIN/employee/request/18/",
  "visible_by_employee": true
}

Errors

HTTP 400 Bad Request: Invalid parameters.

For validation errors, the body of the response contains the list of errors. An optional error code and message can be specified.

HTTP 400 Bad Request
[
    {"start_vacation_date": ["is mandatory"]},
    {"end_vacation_date": ["is not a valid date format"]},
    {"employee_technical_id": ["employee not found"]},
    {"creator_technical_id": ["manager not found"]},
    {"base": ["a global form validation error (for instance cross parameter validations)"]}
]

HTTP 403 Forbidden: Authentication failed.

{
    "detail": "Forbidden."
}

Sample curl call

curl -v -X POST "https://peopleask.net/api/requests/" \
    -H "Content-type: multipart/form-data" \
    -H "Accept: application/json" \
    -H "X-API-KEY: XXXXXXXXXXXXXX" \
    -F "file_employee_vacation_status=@test.pdf" \
    -F "employee_technical_id=GE15961891" \
    -F "creator_technical_id=GE15961891" \
    -F "form_code=vacation_request" \
    -F "vacation_date_start=2012-01-01T12:00:00+00:00" \
    -F "body=Vacances" \
    -F "subject=Demande de vacance pour février"

Get request

This method gets all the information of a specific request

URL

GET /api/requests/:id/
    Accept: application/json
    Content-Type: application/json
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Response

Success

The response is encoded in the JSON format with the following parameters:

Parameter

Description

Type

Exemple

id

The id of the request

INTEGER

789

form

Code of the form

OBJECT

{…}

subject

Subject of the request (can be set by the creator of the request or automatically generated depending on the form)

VARCHAR(256)

What’s the company vacation policy?

body

Request body (html)

TEXT

… long body ….

body_json

Request body (json), if the form is a custom form

JSON

origin

Origin (can be set by the creator of the request if the request is pmade by a manager)

ENUM(PEOPLASK,EMAIL,PHONE,API)

PEOPLASK

status

State of the request

ENUM(created,open,pending,closed)

created

custom_state

Custom state of the request (possibly set in the processing rules)

VARCHAR(100)

Manager validation pending

employee

Employee related to this request

OBJECT

{…}

creator

Creator of this request (can be the employee himself, or a manager)

OBJECT

{…}

managers_assigned

List of managers assigned to this request (at the time of the API call)

LIST

[{…},{…},…]

processing_date_due

Due date of this request (can be calculated / overridden by a automatic processing rule)

DATETIME

2012-01-01T12:00:00+00:00

processing_start_date

Processing start date of this request (can be calculated / overridden by a automatic processing rule)

DATETIME

2012-01-01T12:00:00+00:00

created_at

Creation date of this request (date of the api call)

DATETIME

2012-01-01T12:00:00+00:00

updated_at

Last update of the request

DATETIME

2012-01-01T12:00:00+00:00

closed_by

The manager who closed the request if the request is closed and if known. If it has been reopened, then closed again, the last manager who closed the request is returned.

OBJECT

{…}

closed_at

Last date the request has been closed

DATETIME

2012-01-01T12:00:00+00:00

manager_url

The URL of the request in Request Manager (needs manager authentication)

URL

https://xxxx.peopleask.com/

employee_url

The URL of the request in Request Manager employee portal (needs employee authentication)

URL

https://xxxx.peopleask.com/

api_url

The URI of the request (needs API authentication)

URL

https://xxxx.peopleask.com/

visible_by_employee

Indicates if the request is visible by employees

BOOLEAN

true

HTTP 200 OK:

HTTP/1.1 200 OK
{
  "id": "678",
  "form": {
    "slug": "onboarding-form",
    "title": "Welcome!!",
    "category": {
        "slug": "onboarding",
        "name": "OnBoarding Section!",
        "language_code": "en",
        "description": "..."
    },
    "featured": false,
    "total_hits": 5678,
    "updated_at": "2012-01-01T12:00:00+00:00",
    "created_at": "2012-01-01T12:00:00+00:00",
    "api_url": "https://API_DOMAIN/api/forms/:slug/",
   }
  "subject": "Ticket subject",
  "body": "<div>...</div>",
  "body_json": {
    "start_vacation_date": "2012-01-01T12:00:00+00:00",
    "comment": "Thank you for validating this request \n Regards",
    "file_employee_vacation_status": "/ticket/requests/567/file/56789/"
  },
  "origin": "PEOPLASK",
  "status": "closed",
  "custom_state": "",
  "category": "Vacancies",
  "employee": {
    "technical_id": "NT7896789",
    "first_name": "Bill",
    "last_name": "Riveman",
    "email": "employee333@example.com"
  },
  "creator": {
    "technical_id": "H86789678",
    "first_name": "Jonh",
    "last_name": "Steinberg",
    "email": "manager78990@example.com"
  },
  "managers_assigned": [
    {
      "technical_id": "KLU907",
      "first_name": "Natalie",
      "last_name": "Steinberg",
      "email": "manager7grt0@example.com"
    },
    {
      "technical_id": "HG789Y79",
      "first_name": "Manuel",
      "last_name": "Bisho",
      "email": "manager7530@example.com"
    }
  ],
  "processing_date_due": "2012-01-01T12:00:00+00:00",
  "processing_start_date": "2012-01-01T12:00:00+00:00",
  "created_at": "2012-01-01T12:00:00+00:00",
  "updated_at": "2012-01-01T12:00:00+00:00",
  "closed_by": {
    "technical_id": "KLU907",
    "first_name": "Natalie",
    "last_name": "Steinberg",
    "email": "manager7grt0@example.com"
  },
  "closed_at": "2012-01-01T12:00:00+00:00",
  "api_url": "https://API_DOMAIN/api/request/18/",
  "manager_url": "https://CLIENT-SUBDOMAIN/manager/request/18/",
  "employee_url": "https://CLIENT-SUBDOMAIN/employee/request/18/",
  "visible_by_employee": true
}

Errors

HTTP 400 Bad Request: Invalid parameters.

HTTP 404 Not Found: Request id not found.

HTTP 403 Forbidden: Authentication failed.

Sample curl call

curl -v -X GET "https://peopleask.net/api/requests/567/" \
    -H "Content-type: multipart/form-data" \
    -H "Accept: application/json" \
    -H "X-API-KEY: XXXXXXXXXXXXXX"

List and Search requests

This method returns all requests based the query parameters.

URL

GET /api/requests/?...
    Accept: application/json
    Content-Type: application/json
    X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxx

Parameters

Search filters:

Parameter

Description

Type

mandatory

Exemple

form_code

Code of the form

VARCHAR(20)

optional

form_code: onboarding

employee_technical_id

Filter request of this employee

VARCHAR(50)

optional

employee_technical_id: XAQ678900

creator_technical_id

Filter request created by this user (can be an employee or a manager)

VARCHAR(50)

optional

creator_technical_id: XAQ678900

status

Status of the request. Can be created, opened, pending, closed

ENUM

optional

status: created

origin

Origin of the request. Can be PEOPLASK, EMAIL, PHONE

ENUM

optional

origin: PEOPLASK

created_at_since

Minimum date of creation

DATETIME

optional

created_at_since: 2012-01-01T12:00:00+00:00

created_at_until

Maximum date of creation

DATETIME

optional

created_at_until: 2012-01-01T12:00:00+00:00

closed_at_since

Minimum closing date

DATETIME

optional

closed_at_since: 2012-01-01T12:00:00+00:00

closed_at_until

Maximum closing date

DATETIME

optional

closed_at_until: 2012-01-01T12:00:00+00:00

visible_by_technical_id

Filter requests visible by this employee

VARCHAR(50)

optional

visible_by_technical_id: XAQ678900

visible_by_novacore_uuid

Filter requests visible by this employee

UUID

optional

visible_by_novacore_uuid: 5da3506e-14ce-4478-8d6b-b345671adb22

Ordering and pagination:

Parameter

Description

Type

mandatory

Exemple

order_by

Ordering rule. Specify an attribute of a request, with a possible unary negative to imply descending sort order.

ATTRIBUTE

optional

order_by: -created_at

per_page

Number of request per page (defaults to 20, max 100)

INTEGER

optional

per_page: 50

page

Page number (defaults to 1)

INTEGER

optional

page: 2

Response

Success

The response is encoded in the JSON format with the following parameters and is a list of request objects with the following attributes:

Parameter

Description

Type

Exemple

id

The id of the request

INTEGER

789

form

Code of the form

OBJECT

{…}

subject

Subject of the request (can be set by the creator of the request or automatically generated depending on the form)

VARCHAR(256)

What’s the company vacation policy?

body

Request body (html)

TEXT

… long body ….

body_json

Request body (json), if the form is a custom form

JSON

origin

Origin (can be set by the creator of the request if the request is pmade by a manager)

ENUM(PEOPLASK,EMAIL,PHONE,API)

PEOPLASK

status

State of the request

ENUM(created,open,pending,closed)

created

custom_state

Custom state of the request (possibly set in the processing rules)

VARCHAR(100)

Manager validation pending

employee

Employee related to this request

OBJECT

{…}

creator

Creator of this request (can be the employee himself, or a manager)

OBJECT

{…}

managers_assigned

List of managers assigned to this request (at the time of the API call)

LIST

[{…},{…},…]

processing_date_due

Due date of this request (can be calculated / overridden by a automatic processing rule)

DATETIME

2012-01-01T12:00:00+00:00

processing_start_date

Processing start date of this request (can be calculated / overridden by a automatic processing rule)

DATETIME

2012-01-01T12:00:00+00:00

created_at

Creation date of this request (date of the api call)

DATETIME

2012-01-01T12:00:00+00:00

updated_at

Last update of the request

DATETIME

2012-01-01T12:00:00+00:00

closed_by

The manager who closed the request if the request is closed and if known. If it has been reopened, then closed again, the last manager who closed the request is returned.

OBJECT

{…}

closed_at

Last date the request has been closed

DATETIME

2012-01-01T12:00:00+00:00

manager_url

The URL of the request in Request Manager (needs manager authentication)

URL

https://xxxx.peopleask.com/

employee_url

The URL of the request in Request Manager employee portal (needs employee authentication)

URL

https://xxxx.peopleask.com/

api_url

The URI of the request (needs API authentication)

URL

https://xxxx.peopleask.com/

visible_by_employee

Indicates if the request is visible by employees

BOOLEAN

true

For instance:

HTTP 200 OK:

HTTP/1.1 200 OK
Link: <https://BASE_URL/manager/requests/?page=2&per_page=30>; rel="previous",
      <https://BASE_URL/manager/requests/?page=4&per_page=30>; rel="next"
X-Total-Count: 158
[
  {request_object_1},
  ...,
  {request_object_2}
]

Where request_object_x is a json like this:

{
  "id": "678",
  "form": {
    "slug": "onboarding-form",
    "title": "Welcome!!",
    "category": {
        "slug": "onboarding",
        "name": "OnBoarding Section!",
        "language_code": "en",
        "description": "..."
    },
    "featured": false,
    "total_hits": 5678,
    "updated_at": "2012-01-01T12:00:00+00:00",
    "created_at": "2012-01-01T12:00:00+00:00",
    "api_url": "https://API_DOMAIN/api/forms/:slug/",
   }
  "subject": "Ticket subject",
  "body": "<div>...</div>",
  "body_json": {
    "start_vacation_date": "2012-01-01T12:00:00+00:00",
    "comment": "Thank you for validating this request \n Regards",
    "file_employee_vacation_status": "/ticket/requests/567/file/56789/"
  },
  "origin": "PEOPLASK",
  "status": "closed",
  "custom_state": "",
  "category": "Vacancies",
  "employee": {
    "technical_id": "NT7896789",
    "first_name": "Bill",
    "last_name": "Riveman",
    "email": "employee333@example.com"
  },
  "creator": {
    "technical_id": "H86789678",
    "first_name": "Jonh",
    "last_name": "Steinberg",
    "email": "manager78990@example.com"
  },
  "managers_assigned": [
    {
      "technical_id": "KLU907",
      "first_name": "Natalie",
      "last_name": "Steinberg",
      "email": "manager7grt0@example.com"
    },
    {
      "technical_id": "HG789Y79",
      "first_name": "Manuel",
      "last_name": "Bisho",
      "email": "manager7530@example.com"
    }
  ],
  "processing_date_due": "2012-01-01T12:00:00+00:00",
  "processing_start_date": "2012-01-01T12:00:00+00:00",
  "created_at": "2012-01-01T12:00:00+00:00",
  "updated_at": "2012-01-01T12:00:00+00:00",
  "closed_by": {
    "technical_id": "KLU907",
    "first_name": "Natalie",
    "last_name": "Steinberg",
    "email": "manager7grt0@example.com"
  },
  "closed_at": "2012-01-01T12:00:00+00:00",
  "api_url": "https://API_DOMAIN/api/request/18/",
  "manager_url": "https://CLIENT-SUBDOMAIN/manager/request/18/",
  "employee_url": "https://CLIENT-SUBDOMAIN/employee/request/18/",
  "visible_by_employee": true
}

Errors

HTTP 400 Bad Request: Invalid parameters.

HTTP 403 Forbidden: Authentication failed.

Sample curl call

curl -v -X GET "https://peopleask.net/api/requests/?form_code=onboarding&status=closed&closed_at_since=2012-01-01T00:00:00+00:00&closed_at_until=2012-01-02T00:00:00+00:00&order_by=-closed_at" \
    -H "Content-type: application/json" \
    -H "Accept: application/json" \
    -H "X-API-KEY: XXXXXXXXXXXXXX"