WorkSchedule.Net REST / JSON Interface

WorkSchedule.Net v9 API

Developer Help Documentation — Complete RESTful HTTPS programmatic integration and JSON data interchange reference.

Overview

The WorkSchedule.Net API enables programmatic functionality and the interchange of data with third-party software applications.

Prerequisites

To get started, you need the following:

Company Account: An active WorkSchedule.Net company account.
API User Account: An active user account within that company account with permissions to access the API (see the Roles topic in the Help Documentation). We recommend using a single dedicated user and role for API purposes.

Once these prerequisites are in place, you can start making HTTPS calls using the specifications below.

Specification	Value
Base URL (Endpoint)	`https://api.workschedule.app/`
Supported Formats	JSON (input and output)
Supported Methods	REST-standard HTTP methods: `GET`, `POST`, `PUT`, `DELETE`
Required Version Header	`X-Api-Version: 1.1` (required in HTTP headers for the latest API version)

Obtaining Access and Authorization

To access the API methods, you must first obtain a session API key and password. Call the StartAPISession method by appending StartAPISession to the base URL (https://api.workschedule.app/) followed by a ? and the following query string parameters separated by &:

CompanyID= Your WorkSchedule.Net CompanyID
UserName= The username of the API-designated user account
Passcode= The password of the API-designated user account (URL-encoded)

Example Request URL:

https://api.workschedule.app/StartAPISession?CompanyID=12345&UserName=APIUser&Passcode=12345689ab%23

Sample JSON Response:

{
    "SessionError": "0",
    "SessionInformation": {
        "SessionID": 11093,
        "SessionPassword": "2109769271"
    }
}

Include the returned SessionID and SessionPassword (abbreviated as SP) in the query parameters for every subsequent HTTP API request:

https://api.workschedule.app/<Entity>?SessionID=11093&SP=2109709271

HTTP Request Headers

Standard HTTP request headers are passed as key-value pairs to specify API versioning, target calendar routing, and unique entity lookup keys.

Required API Version Header (v1.1): To target the latest version of the API, you must include X-Api-Version: 1.1 in your HTTP request headers.

Header Key	Example Value	Required	Description
`X-Api-Version`	`1.1`	Yes (v1.1)	Specifies the API version. Must be set to `1.1` to access the latest version.
`Lookup-Key`	`TimeBlockID`	Conditional	Identifies the entity property used as the unique lookup key on single-entity requests.
`Calendar-Key`	`CalendarName`	Conditional	Specifies whether Timeblock endpoints use `CalendarName` or `CalendarID`.

URL Format and Structure

Base API Call URL

All API calls begin with the base endpoint URL: https://api.workschedule.app/

Entity Call

Append the target entity name directly after the base URL: https://api.workschedule.app/User

Entity Parameters

Append any entity lookup value(s) after the entity: https://api.workschedule.app/User/1

Authentication Query Parameters

Use a ? after the base URL, entity, and entity parameters to designate the authentication query string. Pass the SessionID and SessionPassword received from StartAPISession using SessionID= and SP=, separated by &.

Example Authenticated Request URL:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: UserID

https://api.workschedule.app/User/1?SessionID=12345&SP=1234567890123

Data Conventions and API Notes

URL Encoding: Special characters must be properly URL-encoded when passed in query parameters (e.g., encoding # as %23).
Date and Time Format: All dates and times are returned in ISO-8601 format in responses. Only ISO-8601 format is officially supported in requests, though the API may adjust to other formats if ISO-8601 is not provided.
Local Time / Time Zone Translation: Dates and times are interpreted as local to the Time Zone “Location” of the Default View of the API user for both requests and responses. Exception: No time zone translation is performed for the Start Date and End Date of Time Off Account category items, as they are time zone agnostic.
Required Fields: An asterisk (*) next to a property or parameter indicates that it is required.
Color Coding: Generally, request text is shown in blue and response text is shown in red.

API Methods

Select an entity below to jump directly to its endpoint methods, parameters, and sample payloads:

USER ENTITY — User endpoints, parameters, and payloads
TIMEBLOCK ENTITY — Timeblock endpoints, parameters, and payloads
CATEGORYITEM ENTITY — CategoryItem endpoints, parameters, and payloads

WorkSchedule.Net v9 API • Entity Reference

USER ENTITY

Retrieve, add, modify, and delete user accounts within a WorkSchedule.Net company account.

↑ Back to API Methods Directory

Intro to User Entity

The User entity methods provide programmatic access to retrieving, adding, modifying, and deleting user accounts within the company account.

HTTP Header Key/Value Pairs

Header Key	Allowed / Expected Value	Default / Behavior
`X-Api-Version`	`1.1`	Required in HTTP headers to target the latest API version (v1.1).
`Lookup-Key`	`ExternalID` or `UserID`	Applies to `GET`, `PUT`, and `DELETE` when accessing a single user. If omitted or unrecognized, defaults to `ExternalID`.

URL Structure and Query Parameters

Endpoint URL Pattern:

https://api.workschedule.app/User/[UserID or ExternalID]?SessionID=12345&SP=1234567890123

URL Segment	Required	Description
`UserID or ExternalID`	Conditional (Required for PUT & DELETE)	The lookup value matching the property chosen in the `Lookup-Key` header. If excluded on `GET`, all users in the company account are retrieved.

User Entity Methods

Example 1: Retrieve All Users in the Company Account

Sample Request URL #1:

Request Headers: X-Api-Version: 1.1

https://api.workschedule.app/User?SessionID=12345&SP=1234567890123

Sample JSON Response #1:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": "[]",
    "Items": [
        {
            "EMail": "bob.smith@programworks.com",
            "ExternalID": "",
            "FirstName": "Bob",
            "LastName": "Smith",
            "WorkPhone": "",
            "UserID": "1",
            "UserName": "bsmith",
            "UserNotes": "",
            "RoleInfo": {
                "RoleID": 4,
                "RoleDescription": "Administrator"
            }
        },
        {
            "ExternalID": "",
            "FirstName": "Sally",
            "LastName": "MacKay",
            "WorkPhone": "4075551234",
            "UserID": "2",
            "UserName": "SallyMacKay",
            "UserNotes": "",
            "RoleInfo": {
                "RoleID": 1,
                "RoleDescription": "Employee"
            }
        },
        {
            "EMail": "mary.carney@programworks.com",
            "ExternalID": "",
            "FirstName": "API",
            "LastName": "User",
            "WorkPhone": "",
            "UserID": "6",
            "UserName": "APIUser",
            "UserNotes": "",
            "RoleInfo": {
                "RoleID": 4,
                "RoleDescription": "API Role"
            }
        }
    ]
}

Example 2: Retrieve a Single User by UserID

Sample Request URL #2:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: UserID

https://api.workschedule.app/User/5?SessionID=12345&SP=1234567890123

Sample JSON Response #2:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": "[]",
    "Items": {
        "ExternalID": "32",
        "FirstName": "Bob",
        "LastName": "Smith",
        "WorkPhone": "",
        "UserID": "5",
        "UserNotes": "",
        "RoleInfo": {
            "RoleID": 1,
            "RoleDescription": "Employee"
        }
    }
}

JSON Body Parameters

Parameter	Required	Notes / Validation Rules
`UserName*`	Yes	Must be unique, greater than 6 characters, and alphanumeric.
`FirstName*`	Yes	User's first name.
`LastName*`	Yes	User's last name.
`Email*`	Yes	User's email address.
`RoleID*`	Yes	Internal ID of the security role assigned to the user.
`MainDepartment*`	Yes	Category Item ID of the user's primary department.
`HomePhone`	No	User's home phone number.
`WorkPhone`	No	User's work phone number.
`MobilePhone`	No	User's mobile phone number.

Sample Request URL:

Request Headers: X-Api-Version: 1.1

https://api.workschedule.app/User?SessionID=12345&SP=1234567890123

Sample JSON Request (HTTPS Body):

{
    "UserName": "RyanS",
    "FirstName": "Ryan",
    "LastName": "Swift",
    "Email": "ryan.swift@programworks.com",
    "RoleID": "1",
    "MainDepartment": "1",
    "HomePhone": "3055555928"
}

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": "[]"
}

JSON Body Parameters

Parameter	Required	Notes / Validation Rules
`UserName`	No	Must be unique, greater than 6 characters, and alphanumeric.
`FirstName`	No	Updated first name.
`LastName`	No	Updated last name.
`Email`	No	Updated email address.
`RoleID`	No	Updated security RoleID.
`MainDepartment`	No	Updated primary department Category Item ID.
`HomePhone`	No	Updated home phone number.
`WorkPhone`	No	Updated work phone number.
`MobilePhone`	No	Updated mobile phone number.

Sample Request URL:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: UserID (or ExternalID)

https://api.workschedule.app/User/1?SessionID=12345&SP=1234567890123

Sample JSON Request (HTTPS Body):

{
    "HomePhone": "9545555928"
}

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": "[]"
}

Sample Request URL:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: UserID (or ExternalID)

https://api.workschedule.app/User/1?SessionID=12345&SP=1234567890123

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": "[]"
}

WorkSchedule.Net v9 API • Entity Reference

TIMEBLOCK ENTITY

Retrieve, add, modify, and delete shifts and time-off blocks across Schedule and Attendance calendars.

↑ Back to API Methods Directory

Intro to Timeblock Entity

The Timeblock entity methods give access to retrieving, adding, modifying, and deleting time blocks (shifts and time-off blocks) within the company account in both the Schedule and Attendance areas. Access to templates is not currently supported.

HTTP Header Key/Value Pairs

Header Key	Allowed / Expected Value	Default / Behavior
`X-Api-Version`	`1.1`	Required in HTTP headers to target the latest API version (v1.1).
`Lookup-Key`	`ExternalID` or `TimeBlockID`	Applies to `GET`, `PUT`, and `DELETE` when accessing a single entity. If omitted or unrecognized, defaults to `ExternalID`.
`Calendar-Key`	`CalendarID` or `CalendarName`	Specifies how the target calendar (Schedule vs. Attendance) is referenced in the URL. If omitted or unrecognized, defaults to `CalendarName`.

URL Structure and Query Parameters

Endpoint URL Pattern:

https://api.workschedule.app/Timeblock/[CalendarName or CalendarID]/[TimeBlockID or ExternalID]?SessionID=12345&SP=1234567890123

URL Segment	Required	Description
`CalendarName or CalendarID*`	Yes (All verbs)	Target calendar area. If using `CalendarName`, pass `"Schedule"` or `"Attendance"`. If using `CalendarID`, pass `1` (Schedule) or `7` (Attendance).
`TimeBlockID or ExternalID`	Conditional (Required for PUT & DELETE)	Lookup value matching the property chosen in `Lookup-Key`. If excluded on `GET`, all time blocks for the calendar within the `StartTime`/`EndTime` range in the HTTPS body are retrieved.

Timeblock Entity Methods

Example 1: Retrieve Time Blocks for a Calendar Within a Date Range

JSON Body Parameter	Required	Description
`StartTime*`	Yes (when no lookup ID is specified)	Start of the query date/time range in ISO-8601 format.
`EndTime*`	Yes (when no lookup ID is specified)	End of the query date/time range in ISO-8601 format.

Sample Request URL #1:

Request Headers: X-Api-Version: 1.1 | Calendar-Key: CalendarName

https://api.workschedule.app/TimeBlock/Schedule?SessionID=12345&SP=1234567890123

Sample JSON Response #1:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": "[]",
    "Items": [
        {
            "Color": "FFCC99",
            "UserID": "1",
            "EndTime": "2023-12-27T17:01:00.0000000",
            "Notes": "",
            "TimeBlockID": "49168",
            "StartTime": "2023-12-27T09:00:00.0000000",
            "CategoryItems": [
                {
                    "Color": "",
                    "Name": "Main",
                    "CatNo": "1",
                    "CatItemID": "1",
                    "CategoryName": "Location"
                }
            ],
            "EmployeeName": "Mya Collins",
            "TimeOnOff": "On"
        },
        {
            "Color": "FFCC99",
            "EndTime": "2023-12-27T17:00:00.0000000",
            "Notes": "",
            "TimeBlockID": "49175",
            "StartTime": "2023-12-27T09:00:00.0000000",
            "CategoryItems": [
                {
                    "Color": "E0E0E0",
                    "Name": "Main",
                    "CatNo": "1",
                    "CatItemID": "1",
                    "CategoryName": "Location"
                }
            ],
            "EmployeeName": "OPEN",
            "TimeOnOff": "On"
        },
        {
            "UserID": "1",
            "EndTime": "2023-12-28T17:00:00.0000000",
            "Notes": "",
            "TimeBlockID": "49176",
            "StartTime": "2023-12-28T09:00:00.0000000",
            "CategoryItems": [
                {
                    "Color": "",
                    "Name": "Main",
                    "CatNo": "1",
                    "CatItemID": "1",
                    "CategoryName": "Location"
                }
            ],
            "EmployeeName": "Mya Collins",
            "TimeOnOff": "On"
        }
    ]
}

Example 2: Retrieve a Single Time Block by Lookup Key

Sample Request URL #2:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: TimeBlockID

https://api.workschedule.app/TimeBlock/Schedule/49176?SessionID=12345&SP=1234567890123

Sample JSON Response #2:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": "[]",
    "Items": [
        {
            "UserID": "1",
            "EndTime": "2023-12-28T17:00:00.0000000",
            "Notes": "",
            "TimeBlockID": "49176",
            "StartTime": "2023-12-28T09:00:00.0000000",
            "CategoryItems": [
                {
                    "Color": "",
                    "Name": "Main",
                    "CatNo": "1",
                    "CatItemID": "1",
                    "CategoryName": "Location"
                }
            ],
            "EmployeeName": "Mya Collins",
            "TimeOnOff": "On"
        }
    ]
}

JSON Body Parameters

Parameter	Required	Notes / Applicability
`UserID*`	Yes	Assigned user's internal ID. A `UserID` of `"0"` indicates an open time block.
`ExternalID`	No	Optional external system identifier.
`StartTime*`	Yes	Start date and time in ISO-8601 format.
`EndTime*`	Yes	End date and time in ISO-8601 format.
`Notes`	No	Optional text notes attached to the time block.
`Color`	No	6-character hex color code.
`CategoryItems`	No	JSON object mapping each Category name (key) to its Category Item ID (value), e.g., `{"Location": "1", "Area": "11"}`.

Sample Request URL:

Request Headers: X-Api-Version: 1.1

https://api.workschedule.app/TimeBlock/Attendance?SessionID=12345&SP=1234567890123

Sample JSON Request (HTTPS Body):

{
    "UserID": "0",
    "EndTime": "2023-12-28T22:32:00.0000000",
    "StartTime": "2023-12-28T22:32:00.0000000",
    "CategoryItems": {
        "Location": "1",
        "Area": "11"
    }
}

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": []
}

JSON Body Parameters

Parameter	Required	Notes / Applicability
`UserID`	No	Assigned user's internal ID. A `UserID` of `"0"` indicates an open time block.
`ExternalID`	No	Updated external system identifier.
`StartTime`	No	Updated start date and time in ISO-8601 format.
`EndTime`	No	Updated end date and time in ISO-8601 format.
`StartDayNo`	No	Optional start day offset number.
`Notes`	No	Updated text notes.
`Color`	No	Updated 6-character hex color code.
`CategoryItems`	No	JSON object mapping each Category name (key) to its Category Item ID (value).

Sample Request URL:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: TimeBlockID (or ExternalID)

https://api.workschedule.app/TimeBlock/Schedule/88?SessionID=12345&SP=1234567890123

Sample JSON Request (HTTPS Body):

{
    "UserID": "3",
    "Notes": "Updated Notes"
}

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": []
}

Sample Request URL:

Request Headers: X-Api-Version: 1.1 | Calendar-Key: CalendarID | Lookup-Key: TimeBlockID

https://api.workschedule.app/TimeBlock/1/55?SessionID=12345&SP=1234567890123

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": []
}

WorkSchedule.Net v9 API • Entity Reference

CATEGORY ITEM ENTITY

Retrieve, add, modify, and delete category items within a WorkSchedule.Net company account.

↑ Back to API Methods Directory

Intro to Category Item Entity

The Category Item entity methods provide programmatic access to retrieving, adding, modifying, and deleting category items of a specified category (such as “Departments”, “Locations”, “Areas”, “Tasks”, “Times of Day”, and other user-defined categories) within the company account.

HTTP Header Key/Value Pairs

Header Key	Allowed / Expected Value	Default / Behavior
`X-Api-Version`	`1.1`	Required in HTTP headers to target the latest API version (v1.1).
`Lookup-Key`	`ExternalID` or `CatItemID`	Applies to `GET`, `PUT`, and `DELETE` for single-entity requests. If omitted or unrecognized, the API defaults to `ExternalID`.

URL Structure and Query Parameters

Endpoint URL Pattern:

https://api.workschedule.app/CategoryItem/[CatName]/[CatItemID or ExternalID]?SessionID=12345&SP=1234567890123

URL Segment	Required	Description
`CatName*`	Yes (All verbs)	The name of the category (e.g., `Area`, `Location`, `Department`).
`CatItemID or ExternalID`	Conditional (Required for PUT & DELETE)	The lookup value matching the property chosen in the `Lookup-Key` header. If omitted on `GET`, all Category Items for the specified `CatName` are returned.

CategoryItem Entity Methods

Example 1: Retrieve All Items in a Category

Sample Request URL #1:

Request Headers: X-Api-Version: 1.1

https://api.workschedule.app/CategoryItem/Area?SessionID=12345&SP=1234567890123

Sample JSON Response #1:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": "[]",
    "Items": [
        {
            "Color": "",
            "Name": "Area A",
            "CatNo": "2",
            "CatItemID": "10",
            "SortValue": "0000000001"
        },
        {
            "Color": "000000",
            "Name": "Area B",
            "ExternalID": "BArea",
            "CatNo": "2",
            "CatItemID": "11",
            "SortValue": "0000000002"
        },
        {
            "Color": "",
            "Name": "Area C",
            "CatNo": "2",
            "CatItemID": "17",
            "SortValue": "0000000003"
        }
    ]
}

Example 2: Retrieve a Single Category Item by CatItemID

Sample Request URL #2:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: CatItemID

https://api.workschedule.app/CategoryItem/Location/1?SessionID=12345&SP=1234567890123

Sample JSON Response #2:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": "[]",
    "Items": [
        {
            "Active": "False",
            "Color": "",
            "Name": "Main",
            "EndTime": "T17:00:00.0000000",
            "CatNo": "1",
            "CatItemID": "1",
            "ShowToEmployee": "False",
            "SortValue": "0000000001",
            "StartTime": "T09:00:00.0000000"
        }
    ]
}

JSON Body Parameters

Parameter	Required	Notes / Applicability
`Name*`	Yes	Display name of the new category item.
`ExternalID`	No	Optional external system identifier.
`Color`	No	6-character hex color code (e.g., `00FF00`).
`Active`	No	Time Off Account category items only.
`ShowToEmployee`	No	Time Off Account category items only.
`StartTime`	No	Time Of Day category items only.
`EndTime`	No	Time Of Day category items only.

Sample Request URL:

Request Headers: X-Api-Version: 1.1

https://api.workschedule.app/CategoryItem/Location?SessionID=12345&SP=1234567890123

Sample JSON Request (HTTPS Body):

{
    "Name": "Location X",
    "CatNo": "1",
    "Color": "00FF00"
}

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": "[]"
}

JSON Body Parameters

Parameter	Required	Notes / Applicability
`Name`	No	Updated display name of the category item.
`ExternalID`	No	Updated external identifier.
`Color`	No	Updated 6-character hex color code (e.g., `0E0E0E`).
`Active`	No	Time Off Account category items only.
`ShowToEmployee`	No	Time Off Account category items only.
`StartTime`	No	Time Of Day category items only.
`EndTime`	No	Time Of Day category items only.

Sample Request URL:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: CatItemID (or ExternalID)

https://api.workschedule.app/CategoryItem/Location/55?SessionID=12345&SP=1234567890123

Sample JSON Request (HTTPS Body):

{
    "Color": "0E0E0E"
}

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": "[]"
}

Sample Request URL:

Request Headers: X-Api-Version: 1.1 | Lookup-Key: CatItemID (or ExternalID)

https://api.workschedule.app/CategoryItem/Location/8?SessionID=12345&SP=1234567890123

Sample JSON Response:

{
    "ErrorCode": 0,
    "ErrorMessage": "Success",
    "ItemResponses": null,
    "Items": "[]"
}