Forms API¶

Overview
List and Search forms

Overview ¶

A form in UKG HR Service Delivery is a customizable form that can be build by an administrator. Each form is defined by a list of fields and is displayed on the employee portal to be completed by employees.

For employees, the access to a form can be based on:

The organisation perimeter of the employee
Some filtering rules based on the custom attributes of the employee

For managers, the access to a form can be based on the role of the manager.

List and Search forms ¶

This method returns all forms based the query GET parameters.

URL ¶

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

Parameters ¶

Search filters (GET parameters):

Parameter	Description	Type	mandatory	Exemple
category_code	Identifying code (slug) of a category. If set, returns only the forms included in this category.	`VARCHAR(50)`	`optional`	category_code: onboarding
accessible_by	Some forms may be accessible only to employees or managers. When set to `employees`, returns only the employee forms, when set to `managers`, returns only manager forms. If empty or not in the query, all forms are returned.	`ENUM`	`optional`, can be `employees`, `managers`	accessible_by: employees
employee_technical_id	Return only the forms accessible to this specific employee. Note: `accessible_by` should be either `employees` or empty. If empty or not in the query, all forms are returned.	`VARCHAR(50)`	`optional`	employee_technical_id: XAQ678900
manager_technical_id	Return only the forms accessible to this specific manager. Note: `accessible_by` should be either `managers` or empty. If empty or not in the query, all forms are returned.	`VARCHAR(50)`	`optional`	manager_technical_id: MAQ678900
featured	If true, returns only “featured” forms (those forms are displayed on the employee home page), if false, return non “featured” forms. If empty or not in the query, all forms are returned.	`BOOLEAN`	`optional`	featured: true
query	Full text search in the form title	`text`	`optional`	query: Onboarding form

Ordering and pagination:

Parameter	Description	Type	mandatory	Exemple
order_by	Ordering rule. Specify an attribute of a form, with a possible unary negative to imply descending sort order. The attribute can be `created_at`, `updated_at`, `title`, `total_hits`	`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	`INTEGER`	`optional` (defaults to 1)	page: 2

Response ¶

Success¶

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

Parameter	Description	Type	Exemple
slug	The slug of the form, wich is the default unique identifier used in the URI for this form	`VARCHAR(255)`	how-to-complete-the-onboarding-form
title	The title of the form	`VARCHAR(255)`	How to complete the onboarding form?
category	The list of categories of this form	`JSON_OBJECT`	{…}
featured	The featured state of the form	`BOOLEAN`	false
total_hits	Total number of pageviews of this form on the employee portal (API hits are not counted…)	`INTEGER`	1856
updated_at	Last update of the form	`DATETIME`	2012-01-01T12:00:00+00:00
created_at	Creation date of the form	`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/…

For instance:

HTTP 200 OK:

HTTP/1.1 200 OK
Link: <https://BASE_URL/manager/forms/?page=2&per_page=30>; rel="next",
      <https://BASE_URL/manager/forms/?page=5&per_page=30>; rel="last"

[
  {form_object_1},
  ...,
  {form_object_2}
]

Where form_object_x is a json like this:

{
  "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/",
}

Errors¶

HTTP 400 Bad Request: Invalid parameters.

HTTP 403 Forbidden: Authentication failed.

Sample curl call ¶

curl -v -X GET "https://peopleask.net/api/forms/?category_code=onboarding&employee_technical_id=56789G79" \
    -H "Content-type: application/json" \
    -H "Accept: application/json" \
    -H "X-API-KEY: XXXXXXXXXXXXXX"

Forms API¶

Overview¶

List and Search forms¶

URL¶

Parameters¶

Response¶