Humanity Platform API

https://platform.humanity.com/reference
Admin
Humanity Platform API is a comprehensive REST API for managing workforce operations including...
Tokens:346,501
Snippets:797
Trust Score:10
Update:7 months ago
Show doc for...
Tokens:
Raw
### HTTP GET Request Example

Source: https://platform.humanity.com/reference/put-position

Example of an HTTP GET request to retrieve data from the Humanity API. This includes the base URL and an access token for authentication.

```http
https://www.humanity.com/api/v2/positions/1321634?access_token=xxxxxxx
```

--------------------------------

### Perform API POST Request and Client Alert

Source: https://platform.humanity.com/reference/getting-started-with-your-api

Demonstrates how to send data to a specified URL using an HTTP POST request and trigger a browser alert for testing purposes. This snippet relies on a standard HTTP client library common in legacy JavaScript environments.

```javascript
$http.post('/someUrl', data).success(successCallback);

alert('test');
```

--------------------------------

### GET Ratecard Request Example

Source: https://platform.humanity.com/reference/get-ratecard

A sample HTTP request demonstrating how to access the ratecard endpoint using a URL with an access token query parameter.

```html
https://www.humanity.com/api/v2/payroll/ratecards/1?access_token=xxxxxxx
```

--------------------------------

### HTML Body Parameters Example

Source: https://platform.humanity.com/reference/put-position

Example of how to structure body parameters for an HTML request to the Humanity API. This format is typically used for form submissions.

```html
name=Store Manager
active=1
color=27
```

--------------------------------

### GET Data Points - HTTP and cURL Examples

Source: https://platform.humanity.com/reference/get-data-points

This snippet demonstrates how to retrieve data points from the Humanity API using HTTP GET requests. It requires an access token and optionally accepts metric ID, start, and end dates for filtering. The examples provided show the basic structure for making these requests.

```http
https://www.humanity.com/api/v2/demand_driven_scheduling/data-points?access_token=xxxxxxxxxxxx&driver_id=7&start=2020-04-19 20:00:00&end=2020-04-20 22:15:00
```

```curl
curl --location --request GET 'https://www.humanity.com/api/v2/demand_driven_scheduling/data-points?access_token=xxxxxxxxxxxx&driver_id=7&start=2020-04-19 20:00:00&end=2020-04-20 22:15:00'
```

--------------------------------

### HTTP Request Example for Metric Creation

Source: https://platform.humanity.com/reference/create-driver

Example demonstrating the HTTP request format and required body parameters for the metric creation endpoint.

```http
https://www.humanity.com/api/v2/demand_driven_scheduling/metric?access_token=xxxxxxxxxxxx
```

```text
Content-Type=application/x-www-form-urlencoded

name="Metric Name"
increment=60
inherited_forecast_id=124
```

--------------------------------

### GET /settings/platform

Source: https://platform.humanity.com/reference/get-business

Retrieves the current platform configuration settings including SAML integration details and operational preferences.

```APIDOC
## GET /settings/platform

### Description
Retrieves the current platform configuration settings, including SAML authentication parameters and various operational preferences for time tracking and scheduling.

### Method
GET

### Endpoint
/settings/platform

### Request Body
N/A

### Response
#### Success Response (200)
- **promo** (string) - Promotional settings
- **saml_enabled** (string) - Indicates if SAML is active
- **saml_login_url** (string) - SAML login endpoint
- **language** (string) - Default system language
- **daily_overtime** (string) - Daily overtime threshold
- **timezone_id** (string) - System timezone identifier
- **pref_enable_break_button** (string) - Toggle for break button visibility

#### Response Example
{
  "saml_enabled": "0",
  "language": "en_US",
  "daily_overtime": "8",
  "timezone_id": "152",
  "pref_enable_break_button": "1"
}
```

--------------------------------

### GET Note Request Example (HTTP)

Source: https://platform.humanity.com/reference/get-note

This is an example of how to make a GET request to retrieve a note. It requires the note's ID and an access token for authentication. The response will be in JSON format.

```http
https://www.humanity.com/api/v2/notes/123?access_token=xxxxxxx
```

--------------------------------

### HTTP GET Metric Request

Source: https://platform.humanity.com/reference/get-driver

Example of how to make an HTTP GET request to retrieve metric data. This requires an access token and a metric ID. The response will be in JSON format.

```http
https://www.humanity.com/api/v2/demand_driven_scheduling/metric?access_token=xxxxxxxxxxxx&driver_id=7
```

--------------------------------

### GET /notices

Source: https://platform.humanity.com/reference/get-notices

Retrieves a list of system notices. Requires a permission level of 5.

```APIDOC
## GET /notices

### Description
Retrieves a list of all active system notices. This endpoint is restricted to users with a permission level of 5 or higher.

### Method
GET

### Endpoint
/notices

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
GET /notices

### Response
#### Success Response (200)
- **notices** (array) - A list of notice objects containing message content and metadata.

#### Response Example
{
  "notices": [
    {
      "id": 1,
      "message": "System maintenance scheduled for Sunday."
    }
  ]
}
```

--------------------------------

### Start Day Object

Source: https://platform.humanity.com/reference/put-rejecting-leave-request

Details the structure of the 'start_day' object, which contains granular information about a specific day, including its ID, month, day, weekday, year, and week number.

```APIDOC
## Start Day Object

### Description
Represents detailed information about a specific day within a date context.

### Parameters
#### Response Body Fields
- **start_day** (object)
  - **id** (integer) - Example: 3142, Default: 0
  - **month** (integer) - Example: 12, Default: 0
  - **day** (integer) - Example: 5, Default: 0
  - **wday** (integer) - Example: 2, Default: 0
  - **year** (integer) - Example: 2017, Default: 0
  - **weekday** (string) - Example: "Tue"
  - **mname** (string) - Example: "Dec"
  - **week** (integer) - Example: 49, Default: 0
  - **dayid** (integer) - Example: 3, Default: 0
  - **timeid** (integer) - Example: 33, Default: 0
  - **timeid_exact** (integer) - Example: (type not specified, likely integer)

### Response Example
```json
{
  "start_day": {
    "id": 3142,
    "month": 12,
    "day": 5,
    "wday": 2,
    "year": 2017,
    "weekday": "Tue",
    "mname": "Dec",
    "week": 49,
    "dayid": 3,
    "timeid": 33,
    "timeid_exact": 12345
  }
}
```
```

--------------------------------

### GET Leave Types for Employee - OpenAPI Definition

Source: https://platform.humanity.com/reference/get-leave-types-for-a-specific-employee

This snippet defines the GET endpoint for retrieving leave types for a specific employee. It includes details on parameters, responses, and an example JSON payload.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "default",
    "version": "2.0"
  },
  "servers": [
    {
      "url": "https://www.humanity.com/api/v2"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "x-default": "",
        "type": "apiKey",
        "name": "access_token",
        "in": "query"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/employees/{emp_id}/leave-types?access_token=xxxxxxx": {
      "get": {
        "summary": "GET Leave types for a specific employee",
        "description": "/leaves\nPermission level: 7",
        "operationId": "get-leave-types-for-a-specific-employee",
        "parameters": [
          {
            "name": "emp_id",
            "in": "query",
            "description": "Unique ID",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"status\": 1,\n    \"data\": {\n        \"employee_id\": 3475050,\n        \"leave_types\": {\n            \"315263\": {\n                \"enabled\": false,\n                \"entitled\": null\n            },\n            \"326594\": {\n                \"enabled\": false,\n                \"entitled\": null\n            },\n            \"327924\": {\n                \"enabled\": false,\n                \"entitled\": null\n            },\n            \"327926\": {\n                \"enabled\": true,\n                \"entitled\": null,\n                \"remaining\": 21\n            },\n            \"328495\": {\n                \"enabled\": true,\n                \"entitled\": 20,\n                \"remaining\": 20\n            },\n            \"328497\": {\n                \"enabled\": false,\n                \"entitled\": 20\n            }\n        }\n    },\n    \"token\": \"xxxxxxx\",\n    \"error\": null\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "integer",
                      "example": 1,
                      "default": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "employee_id": {
                          "type": "integer",
                          "example": 3475050,
                          "default": 0
                        },
                        "leave_types": {
                          "type": "object",
                          "properties": {
                            "315263": {
                              "type": "object",
                              "properties": {
                                "enabled": {
                                  "type": "boolean",
                                  "example": false,
                                  "default": true
                                },
                                "entitled": {}
                              }
                            },
                            "326594": {
                              "type": "object",
                              "properties": {
                                "enabled": {
                                  "type": "boolean",
                                  "example": false,
                                  "default": true
                                },
                                "entitled": {}
                              }
                            },
                            "327924": {
                              "type": "object",
                              "properties": {
                                "enabled": {
                                  "type": "boolean",
                                  "example": false,
                                  "default": true
                                },
                                "entitled": {}
                              }
                            },
                            "327926": {
                              "type": "object",
                              "properties": {
                                "enabled": {
                                  "type": "boolean",
                                  "example": true,
                                  "default": true
                                },
                                "entitled": {},
                                "remaining": {
                                  "type": "integer",
                                  "example": 21,
                                  "default": 0
                                }
                              }
                            },
                            "328495": {
                              "type": "object",
                              "properties": {
                                "enabled": {
                                  "type": "boolean",
                                  "example": true,
                                  "default": true
                                },
                                "entitled": {},
                                "remaining": {
                                  "type": "integer",
                                  "example": 20,
                                  "default": 0
                                }
                              }
                            },
                            "328497": {
                              "type": "object",
                              "properties": {
                                "enabled": {
                                  "type": "boolean",
                                  "example": false,
                                  "default": true
                                },
                                "entitled": {
                                  "type": "integer",
                                  "example": 20,
                                  "default": 0
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### POST /trainings/modules

Source: https://platform.humanity.com/reference/post-training-modules

Creates a new individual training module. Requires permission level 3.

```APIDOC
## POST /trainings/modules

### Description
Creates an individual training module.

### Method
POST

### Endpoint
/trainings/modules

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **module_name** (string) - Required - The name of the training module.
* **description** (string) - Optional - A detailed description of the training module.
* **content** (string) - Required - The main content of the training module.
* **duration_minutes** (integer) - Optional - The estimated duration of the module in minutes.

### Request Example
```json
{
  "module_name": "Introduction to API Documentation",
  "description": "Learn the basics of creating effective API documentation.",
  "content": "This module covers the importance of clear and concise documentation...",
  "duration_minutes": 60
}
```

### Response
#### Success Response (201 Created)
- **module_id** (string) - The unique identifier for the newly created training module.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "module_id": "mod_12345abc",
  "message": "Training module created successfully."
}
```

#### Error Response (400 Bad Request)
- **error** (string) - Description of the error (e.g., missing required fields, invalid data).

#### Error Response (403 Forbidden)
- **error** (string) - "Permission denied. Requires permission level 3."
```

--------------------------------

### cURL GET Metric Request

Source: https://platform.humanity.com/reference/get-driver

Example of how to make a cURL request to retrieve metric data. This requires an access token and a metric ID. The response will be in JSON format.

```curl
curl --location --request GET 'https://www.humanity.com/api/v2/demand_driven_scheduling/metric?access_token=xxxxxxxxxxxx&driver_id=7'
```

--------------------------------

### POST /trainings/modules

Source: https://platform.humanity.com/reference/post-training-modules

Creates a new training module within the platform. Requires permission level 3.

```APIDOC
## POST /trainings/modules

### Description
Creates a new training module. This endpoint requires an access_token provided as a query parameter.

### Method
POST

### Endpoint
https://www.humanity.com/api/v2/trainings/modules

### Parameters
#### Query Parameters
- **access_token** (string) - Required - API authentication token

#### Request Body
- **title** (string) - Required - The title of the training module
- **contents** (string) - Optional - The text content of the module
- **video** (string) - Optional - Youtube ID for the training video
- **iframe** (string) - Optional - Iframe embed code
- **mintime** (integer) - Optional - Minimum time required for the module
- **section** (integer) - Optional - Section ID
- **tutorial** (integer) - Optional - Tutorial ID

### Request Example
{
  "title": "New training",
  "contents": "Module content here",
  "video": "dQw4w9WgXcQ"
}

### Response
#### Success Response (200)
- **status** (integer) - Status code (1 for success)
- **data** (object) - The created module object
- **token** (string) - Updated session token

#### Response Example
{
    "status": 1,
    "data": {
        "75424": {
            "id": "75424",
            "title": "New training",
            "created": "1522846351"
        }
    },
    "token": "xxxxxxxxx",
    "error": null
}
```

--------------------------------

### GET /budget

Source: https://platform.humanity.com/reference/get-budget

Retrieves the complete set of budget configurations for a specified time period.

```APIDOC
## GET /budget

### Description
Returns all budget settings for a given time period. Requires Permission Level 4.

### Method
GET

### Endpoint
/budget

### Parameters
#### Query Parameters
- **period** (string) - Required - The time period for which to retrieve budget settings.

### Request Example
GET /budget?period=2023-Q4

### Response
#### Success Response (200)
- **budgets** (array) - List of budget objects for the requested period.

#### Response Example
{
	"period": "2023-Q4",
	"budgets": [
		{
			"category": "operations",
			"amount": 50000
		}
	]
}
```

--------------------------------

### Fetch Ratecards via HTTP Request

Source: https://platform.humanity.com/reference/get-billing-packages

A simple HTTP GET request example to retrieve ratecard data. The request requires an 'access_token' query parameter for authorization.

```html
https://www.humanity.com/api/v2/payroll/ratecards?access_token=xxxxxxx
```

--------------------------------

### GET /date-objects

Source: https://platform.humanity.com/reference/get-shift

Retrieves the structure and example data for date objects, including detailed timestamp and calendar information.

```APIDOC
## GET /date-objects

### Description
Returns a detailed date object containing calendar metadata, timestamps, and formatted strings for a specific point in time.

### Method
GET

### Endpoint
/date-objects

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the date record
- **month** (integer) - Month index
- **day** (integer) - Day of the month
- **year** (integer) - Four-digit year
- **formatted** (string) - Human-readable date string
- **timestamp** (integer) - Unix timestamp
- **time** (string) - Time string representation

#### Response Example
{
  "id": 2673,
  "month": 8,
  "day": 23,
  "year": 2016,
  "formatted": "Aug 23, 2016",
  "time": "5:00pm",
  "timestamp": 1471964400
}
```

--------------------------------

### HTTP Request Example for Training Section Update

Source: https://platform.humanity.com/reference/put-training-section

A practical example of how to invoke the training section update endpoint using an HTTP request. It demonstrates the inclusion of the access token as a query parameter.

```http
https://www.humanity.com/api/v2/trainings/sections/123?access_token=xxxxxxx
```

--------------------------------

### HTTP Request for Employee Preclockin

Source: https://platform.humanity.com/reference/get-employees-preclockin

A direct HTTP GET request example to fetch preclockin data for a specific employee ID. The request requires an access_token passed as a query parameter.

```http
https://www.humanity.com/api/v2/employees/123/preclockin?access_token=xxxxxxx
```

--------------------------------

### Forecast API Request and Configuration

Source: https://platform.humanity.com/reference/put-forecastdatatypes

Provides examples for interacting with the forecast API endpoint. Includes an HTTP request example for data retrieval and a text-based representation of the PUT request payload structure.

```http
https://www.humanity.com/api/v2/forecast/datatypes/29?access_token=xxxxxxx
```

```text
name=Forcast - PUT
unique_id=555858
api_locked=0
rules=[{"source_number":"15","need_number":"5","need_product":"1614960","threshold":"2"}]
```

--------------------------------

### GET /sales/budget

Source: https://platform.humanity.com/reference/get-budget

Retrieves budget information for a specified date range. Requires an access token and start and end dates.

```APIDOC
## GET /sales/budget

### Description
Retrieves budget information for a specified date range. This endpoint allows you to fetch budget data, including hours and dollars, for a given period.

### Method
GET

### Endpoint
https://www.humanity.com/api/v2/sales/budget

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your API access token.
- **start_date** (string) - Required - The start date for the budget query (format: YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the budget query (format: YYYY-MM-DD).

### Request Example
```
GET /api/v2/sales/budget?access_token=xxxxx&start_date=2018-10-29&end_date=2018-10-31
```

### Response
#### Success Response (200)
- **status** (integer) - Indicates the success of the operation (1 for success).
- **data** (array) - An array of budget objects, each containing details like id, store, start_date, end_date, location, hours, dollars, and position.

#### Response Example
```json
{
    "status": 1,
    "data": [
        {
            "id": "1297482",
            "store": "303579",
            "start_date": {
                "id": 3470,
                "timestamp": 1540767600,
                "month": 10,
                "day": 29,
                "year": 2018,
                "week": 44,
                "dayid": 2,
                "weekday": "Mon",
                "mname": "Oct",
                "formatted": "Oct 29, 2018"
            },
            "end_date": {
                "id": 3470,
                "timestamp": 1540767600,
                "month": 10,
                "day": 29,
                "year": 2018,
                "week": 44,
                "dayid": 2,
                "weekday": "Mon",
                "mname": "Oct",
                "formatted": "Oct 29, 2018"
            },
            "location": "0",
            "hours": "12.00",
            "dollars": "120.00",
            "position": "0"
        }
    ]
}
```
```

--------------------------------

### POST /budget

Source: https://platform.humanity.com/reference/post-budget

Endpoint to create a new budget entry in the system. Requires permission level 4.

```APIDOC
## POST /budget

### Description
Creates a new budget record in the platform. This operation is restricted to users with permission level 4.

### Method
POST

### Endpoint
/budget

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **budget_name** (string) - Required - The name of the budget
- **amount** (number) - Required - The total budget amount

### Request Example
{
  "budget_name": "Q4 Operations",
  "amount": 50000
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created budget
- **status** (string) - The status of the creation process

#### Response Example
{
  "id": "b-12345",
  "status": "created"
}
```

--------------------------------

### GET /employees/availability/series/{series_id}/slots

Source: https://platform.humanity.com/reference/get-availability-by-series

Retrieves availability slots for a given series ID. This endpoint allows filtering by start and end datetimes.

```APIDOC
## GET /employees/availability/series/{series_id}/slots

### Description
Retrieves availability slots for a given series ID. This endpoint allows filtering by start and end datetimes.

### Method
GET

### Endpoint
https://www.humanity.com/api/v2/employees/availability/series/{series_id}/slots

### Parameters
#### Path Parameters
- **series_id** (string) - Required - The ID of the series for which to retrieve availability.

#### Query Parameters
- **access_token** (string) - Required - Your API access token.
- **start_datetime** (string) - Optional - The start of the date range for filtering availability (DateTime format).
- **end_datetime** (string) - Optional - The end of the date range for filtering availability (DateTime format).

### Request Example
```json
{
  "example": "GET /api/v2/employees/availability/series/0001f8bf2hw74v542wff4a7dw8/slots?access_token=YOUR_ACCESS_TOKEN&start_datetime=2020-05-15T00:00:00+00:00&end_datetime=2020-05-17T23:59:59+00:00"
}
```

### Response
#### Success Response (200)
- **status** (integer) - Indicates the status of the request (1 for success, 0 for failure).
- **data** (array) - An array of availability slot objects.
  - **id** (string) - The unique identifier for the availability slot.
  - **status** (integer) - The status of the availability slot.
  - **employee_id** (integer) - The ID of the employee associated with the slot.
  - **company_id** (integer) - The ID of the company.
  - **start_time** (string) - The start time of the availability slot (DateTime format).
  - **end_time** (string) - The end time of the availability slot (DateTime format).
  - **series_id** (string) - The ID of the series this slot belongs to.
  - **title** (string) - The title of the availability slot.
  - **note** (string) - Any notes associated with the slot.
  - **created_at** (string) - The timestamp when the slot was created (DateTime format).
  - **created_by** (integer) - The ID of the user who created the slot.
  - **updated_at** (string) - The timestamp when the slot was last updated (DateTime format).
  - **updated_by** (integer or null) - The ID of the user who last updated the slot.
  - **deleted_at** (string or null) - The timestamp when the slot was deleted (DateTime format).
  - **deleted_by** (integer or null) - The ID of the user who deleted the slot.
  - **rejected_note** (string or null) - Notes if the slot was rejected.
- **metadata** (array) - Metadata associated with the response.
- **token** (string) - An API token for subsequent requests.
- **error** (object or null) - An error object if the request failed.

#### Response Example
```json
{
  "status": 1,
  "data": [
    {
      "id": "0001f8bf2hw74v542wff4a7dw8",
      "status": 1,
      "employee_id": 2,
      "company_id": 11,
      "start_time": "2020-05-15T13:30:00+02:00",
      "end_time": "2020-05-15T15:00:00+02:00",
      "series_id": "0001f8bf2hw74v542wff4a7dw8",
      "title": "",
      "note": "",
      "created_at": "2020-04-02T12:20:01+02:00",
      "created_by": 2,
      "updated_at": "2020-04-02T22:25:55+02:00",
      "updated_by": null,
      "deleted_at": null,
      "deleted_by": null,
      "rejected_note": null
    }
  ],
  "metadata": [],
  "token": "xxxxxxxxxx",
  "error": null
}
```
```

--------------------------------

### Example API Response for Employee Work Data

Source: https://platform.humanity.com/reference/get-payroll-report

Illustrates a successful (200 OK) API response containing detailed work information for multiple employee entries. Includes user details, dates, times, hours worked, and associated position and rate card information.

```json
{
  "status": 1,
  "data": {
    "0": {
      "userid": "3475064",
      "employee": "Dave Murray",
      "eid": "",
      "date": {
        "id": 3170,
        "timestamp": 1514869200,
        "month": 1,
        "day": 2,
        "year": 2018,
        "week": 1,
        "dayid": 3,
        "weekday": "Tue",
        "mname": "Jan",
        "formatted": "Jan 2, 2018"
      },
      "out_date": {
        "id": 3170,
        "timestamp": 1514869200,
        "month": 1,
        "day": 2,
        "year": 2018,
        "week": 1,
        "dayid": 3,
        "weekday": "Tue",
        "mname": "Jan",
        "formatted": "Jan 2, 2018"
      },
      "start_time": "01:00",
      "end_time": "09:00",
      "hours": {
        "regular": 8,
        "special": 0,
        "overtime": 0,
        "d_overtime": 0,
        "total": 8,
        "cost": 0,
        "breaks": 0,
        "rate": "",
        "position": {
          "id": "1614960",
          "active": "1",
          "notify": "1",
          "store": "303579",
          "user": "3475050",
          "name": "Supervisor",
          "start": "0",
          "end": "0",
          "location": "0",
          "color": "25",
          "ical": "534861a381743f1548d08f1669c3eb62",
          "visible": "1",
          "job_code": null,
          "unique_id": null,
          "skill_id": null
        },
        "ratecard": {
          "id": 265933,
          "name": "Default Card",
          "pay_code": null,
          "override_payroll": "0"
        },
        "location": {
          "id": "",
          "name": ""
        },
        "remote_site": "",
        "base_wage": "",
        "weekly_by_rate": [],
        "daily_by_rate": [],
        "special_by_rate": []
      },
      "overnight": false,
      "clock": "456511406",
      "shift_title": "",
      "in_location_name": "",
      "out_location_name": ""
    },
    "1": {
      "userid": "3475064",
      "employee": "Dave Murray",
      "eid": "",
      "date": {
        "id": 3171,
        "timestamp": 1514955600,
        "month": 1,
        "day": 3,
        "year": 2018,
        "week": 1,
        "dayid": 4,
        "weekday": "Wed",
        "mname": "Jan",
        "formatted": "Jan 3, 2018"
      },
      "out_date": {
        "id": 3171,
        "timestamp": 1514955600,
        "month": 1,
        "day": 3,
        "year": 2018,
        "week": 1,
        "dayid": 4,
        "weekday": "Wed",
        "mname": "Jan",
        "formatted": "Jan 3, 2018"
      },
      "start_time": "01:00",
      "end_time": "08:00",
      "hours": {
        "regular": 7,
        "special": 0,
        "overtime": 0,
        "d_overtime": 0,
        "total": 7,
        "cost": 0,
        "breaks": 0,
        "rate": "",
        "position": {
          "id": "1614960",
          "active": "1",
          "notify": "1",
          "store": "303579",
          "user": "3475050",
          "name": "Supervisor",
          "start": "0",
          "end": "0",
          "location": "0",
          "color": "25",
          "ical": "534861a381743f1548d08f1669c3eb62",
          "visible": "1"
        },
        "ratecard": {
          "id": 265933,
          "name": "Default Card",
          "pay_code": null,
          "override_payroll": "0"
        },
        "location": {
          "id": "",
          "name": ""
        },
        "remote_site": "",
        "base_wage": "",
        "weekly_by_rate": [],
        "daily_by_rate": [],
        "special_by_rate": []
      },
      "overnight": false,
      "clock": "456511406",
      "shift_title": "",
      "in_location_name": "",
      "out_location_name": ""
    }
  }
}
```

--------------------------------

### Example API Response for Task Activity

Source: https://platform.humanity.com/reference/update-employee-tasks

This is an example JSON response from the employee task activity API. It details the status of the task, timestamps for when it was started and ended, the users who performed these actions, and associated metadata. The 'error' field is null for successful operations.

```json
{
    "status": 1,
    "data": {
        "activity": {
            "startedAt": "2025-10-06T09:38:33+00:00",
            "endedAt": "2025-10-07T10:31:47+00:00",
            "startedBy": 2,
            "endedBy": 2,
            "status": 2
        }
    },
    "metadata": [],
    "token": "token",
    "error": null
}
```

--------------------------------

### GET /websites/platform_humanity_reference

Source: https://platform.humanity.com/reference/get-budget

Retrieves reference data for the Platform Humanity project. This endpoint returns a list of events with their start and end dates, locations, hours, and dollar amounts.

```APIDOC
## GET /websites/platform_humanity_reference

### Description
Retrieves reference data for the Platform Humanity project. This endpoint returns a list of events with their start and end dates, locations, hours, and dollar amounts.

### Method
GET

### Endpoint
/websites/platform_humanity_reference

### Parameters
#### Query Parameters
- **token** (string) - Optional - Authentication token.

### Response
#### Success Response (200)
- **status** (integer) - Indicates the success of the operation (1 for success, 0 for failure).
- **data** (array) - An array of event objects.
  - **id** (string) - The unique identifier for the event.
  - **store** (string) - The identifier for the store associated with the event.
  - **start_date** (object) - An object containing details about the start date.
    - **id** (integer) - The unique identifier for the date.
    - **timestamp** (integer) - The Unix timestamp for the date.
    - **month** (integer) - The month of the year (1-12).
    - **day** (integer) - The day of the month (1-31).
    - **year** (integer) - The year.
    - **week** (integer) - The week number of the year.
    - **dayid** (integer) - An identifier for the day of the week (e.g., 1 for Sunday).
    - **weekday** (string) - The abbreviated name of the day of the week (e.g., "Sun").
    - **mname** (string) - The abbreviated name of the month (e.g., "Nov").
    - **formatted** (string) - The date formatted as "Mon Day, Year" (e.g., "Nov 1, 2018").
  - **end_date** (object) - An object containing details about the end date (same structure as start_date).
  - **location** (string) - The location identifier.
  - **hours** (string) - The number of hours associated with the event.
  - **dollars** (string) - The dollar amount associated with the event.
  - **position** (string) - The position identifier.
- **metadata** (array) - An array for metadata, typically empty.
- **token** (string) - The authentication token (may be returned for re-use).
- **error** (null) - Indicates if there was an error (null if no error).

#### Response Example
```json
{
    "status": 1,
    "data": [
        {
            "id": "1297482",
            "store": "303579",
            "start_date": {
                "id": 3470,
                "timestamp": 1540940400,
                "month": 11,
                "day": 1,
                "year": 2018,
                "week": 44,
                "dayid": 5,
                "weekday": "Thu",
                "mname": "Nov",
                "formatted": "Nov 1, 2018"
            },
            "end_date": {
                "id": 3470,
                "timestamp": 1540940400,
                "month": 11,
                "day": 1,
                "year": 2018,
                "week": 44,
                "dayid": 5,
                "weekday": "Thu",
                "mname": "Nov",
                "formatted": "Nov 1, 2018"
            },
            "location": "0",
            "hours": "2.00",
            "dollars": "12.00",
            "position": "0"
        }
    ],
    "metadata": [],
    "token": "xxxxxxxxxxx",
    "error": null
}
```
```

--------------------------------

### Fetch Employee Availability (HTTP, cURL)

Source: https://platform.humanity.com/reference/get-availability-in-date-period

This snippet demonstrates how to fetch employee availability data using HTTP requests. It includes examples for setting up headers and sending body parameters, particularly for cURL requests. The endpoint requires an access token and accepts parameters like start_date, end_date, employee_ids, and status.

```http
https://www.humanity.com/api/v2/employees/availability?access_token=xxxxxxxxxxxxx
```

```text
Content-Type=application/x-www-form-urlencoded
```

```curl
start_date=2020-05-15T00:00:00-05:00
end_date=2020-05-31T00:00:00-05:00
employee_ids=2,3
status=1
```

```curl
curl --location --request POST 'https://www.humanity.com/api/v2/employees/availability?access_token=xxxxxxxxxxxxx' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'start_date=2020-05-15T00:00:00-05:00' \
--data-urlencode 'end_date=2020-05-31T00:00:00-05:00' \
--data-urlencode 'employee_ids=4807410,1417042,2834065' \
--data-urlencode 'status=1'
```

--------------------------------

### Retrieve Master Tasks with Query Parameters

Source: https://platform.humanity.com/reference/get-master-tasks

This example demonstrates how to call the GET Master Tasks endpoint using various query parameters for searching, filtering, and pagination. It shows how to specify search terms, enable description search, filter by position IDs, include deleted records, and control pagination limits and cursors.

```HTTP
GET {baseUrl}/api/v2/master-tasks?access_token={token}&searchTerm=Write&descriptionSearchEnabled=true&positionIds[]=367&includeDeleted=true&limit=10&cursor=some_cursor_value
```

--------------------------------

### POST /skills

Source: https://platform.humanity.com/reference/post-skills

Creates a new skill in the system. Requires a permission level of 5 and an access token.

```APIDOC
## POST /skills

### Description
Creates a new skill. This endpoint requires a permission level of 5.

### Method
POST

### Endpoint
https://www.humanity.com/api/v2/skills

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The authentication token for the API.

#### Request Body
- **name** (string) - Required - The name of the skill to be created.

### Request Example
```json
{
  "name": "JQuery"
}
```

### Response
#### Success Response (200)
- **status** (integer) - Status code of the operation.
- **data** (object) - Contains the created skill details (id, title).
- **token** (string) - Updated access token.
- **error** (null) - Error details if any.

#### Response Example
```json
{
  "status": 1,
  "data": {
    "id": "1496",
    "title": "JQuery"
  },
  "token": "xxxxxxx",
  "error": null
}
```
```

--------------------------------

### GET /api/settings

Source: https://platform.humanity.com/reference/get-business

Retrieves the current configuration settings for the platform, including login methods, time clock parameters, and notification preferences.

```APIDOC
## GET /api/settings

### Description
Retrieves the system-wide and user-specific configuration settings object.

### Method
GET

### Endpoint
/api/settings

### Parameters
None

### Request Example
GET /api/settings

### Response
#### Success Response (200)
- **pref_login_facebook** (integer) - Facebook login enabled status
- **pref_login_twitter** (string) - Twitter login enabled status
- **pref_scosting** (string) - Costing preference configuration
- **settings** (string) - JSON string containing detailed platform settings including timezone, language, and time clock modules.

#### Response Example
{
  "pref_login_facebook": 0,
  "pref_login_twitter": "1",
  "pref_scosting": "3",
  "settings": "{\"pref_timeclock\":\"1\",\"timezone_id\":\"152\",\"language\":\"en_US\"}"
}
```

--------------------------------

### HTTP Request for Daily Peak Hours

Source: https://platform.humanity.com/reference/get-daily-peak-hours-report

A simple HTTP GET request example demonstrating how to access the endpoint with an authentication token. Replace 'xxxxxxx' with a valid access_token to retrieve data.

```http
https://www.humanity.com/api/v2/reports/daily_peak_hours?access_token=xxxxxxx
```

--------------------------------

### OpenAPI Definition for GET Metric

Source: https://platform.humanity.com/reference/get-driver

The OpenAPI 3.1.0 definition for the GET /demand_driven_scheduling/metric endpoint. It specifies the request parameters, authentication methods, and response structure.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "default",
    "version": "2.0"
  },
  "servers": [
    {
      "url": "https://www.humanity.com/api/v2"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "x-default": "",
        "type": "apiKey",
        "name": "access_token",
        "in": "query"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/demand_driven_scheduling/metric": {
      "get": {
        "summary": "GET Metric",
        "description": "/demand_driven_scheduling/metric",
        "operationId": "get-driver",
        "parameters": [
          {
            "name": "access_token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric_id",
            "in": "query",
            "description": "Metric ID",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Response": {
                    "value": "{\n    \"status\": 1,\n    \"data\": {\n        \"id\": 7,\n        \"name\": \"Company Metric\",\n        \"increment\": 60,\n        \"inherited_forecast_id\": 26\n    },\n    \"metadata\": [],\n    \"token\": \"xxxxx\",\n    \"error\": null\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "integer",
                      "example": 1,
                      "default": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 7,
                          "default": 0
                        },
                        "name": {
                          "type": "string",
                          "example": "Company Metric"
                        },
                        "increment": {
                          "type": "integer",
                          "example": 60,
                          "default": 0
                        },
                        "inherited_forecast_id": {
                          "type": "integer",
                          "example": 26,
                          "default": 0
                        }
                      }
                    },
                    "metadata": {
                      "type": "array"
                    },
                    "token": {
                      "type": "string",
                      "example": "xxxxx"
                    },
                    "error": {}
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {
          "code-samples": [
            {
              "language": "http",
              "code": "https://www.humanity.com/api/v2/demand_driven_scheduling/metric?access_token=xxxxxxxxxxxx&driver_id=7",
              "name": "HTTP example"
            },
            {
              "language": "curl",
              "code": "curl --location --request GET 'https://www.humanity.com/api/v2/demand_driven_scheduling/metric?access_token=xxxxxxxxxxxx&driver_id=7'",
              "name": "cURL example"
            }
          ],
          "samples-languages": [
            "http",
            "curl"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

--------------------------------

### GET Timeclock Location (HTTP)

Source: https://platform.humanity.com/reference/get-timeclock-location

This code snippet demonstrates how to make an HTTP GET request to retrieve timeclock locations. It requires an `access_token` query parameter. The response is in JSON format and includes details about each location.

```http
https://www.humanity.com/api/v2/timeclocks/locations?access_token=xxxxxxx
```
Tokens:
Raw