API Management of Recipient List

Tim Shelton

Updated October 21, 2026 17:37

Implementation Steps

Task	Responsible Party
Provide API endpoint access details and credentials	FacilityOS
Set up automated job to manage Recipient data	Client
Review data and confirm accuracy	Client

API

Authentication: OAuth

Format: JSON

Data Flow

For each recipient in each profile, create or update the recipient details in FacilityOS to ensure the latest information is available. For updates, it is recommended to only send updates for records that have recently changed.

Recommended Process:

Confirm if record exists in profile and get details via GET /api/v1/Recipients/RecipientDetails
If record does not exist, add it via POST /api/v1/Recipients/Recipients
If record exists and needs updated, update it via PATCH /api/v1/Recipients/Recipients
If record exists and does not need updated, do nothing further

Fields

Friendly Name	Data Type	Required	Description
empID	String(50)	Yes	An alphanumeric unique identifier for the record. Examples include Employee ID, Timekeeper ID, AD Username, and Email Address. This value must not change
fullName	String(50)	Yes	For people, supply legal fullname in the format lastName, firstName
preferredName	String(50)	No	For use when preferred name is different from legal name
cardID	String(50)	No	Card ID
phoneNumber	String(50)	Yes*	*Required to send text/SMS notification from LogisticsOS
department	String(50)	No
deliveryLocation	String(50)	Yes*	*Use either: deliveryLocation, or At least one of building, room, and floor
building	String(50)	Yes*	*Use either: deliveryLocation, or At least one of building, room, and floor
floor	String(50)	Yes*	*Use either: deliveryLocation, or At least one of building, room, and floor
room	String(50)	Yes*	*Use either: deliveryLocation, or At least one of building, room, and floor
mailStop	String(50)	No	Add on required to use this field
Field10	String(50)	No	Optional customer-defined field. If including this field, advise your FacilityOS implementation contact to enable this field and label it within the UI.
emailAddress	String(641)	Yes*	*Required to send email notification from LogisticsOS
download	Integer	Yes	Distinguishes the source of a record. LogisticsOS natively uses the following: 0 = manually created by end user via UI 1 = imported by end user via UI FacilityOS recommends starting with 2 and incrementing for additional sources.
dynamic	Integer	Yes	Differentiates people and location records. Expected values: 0 = Location 1 = Person
status	Integer	Yes	Specifies whether the record is active. Expected values: 0 = Inactive 1 = Active
profileId	Integer	Yes	The LogisticsOS profieID. Consult your FacilityOS implementation contact for the correct value(s).

Endpoints

Confirm Recipient Exists / Get a Recipient Details

Endpoint: GET /api/v1/Recipients/RecipientDetails

For additional endpoint details, including status codes, see full specification. Note: This reference is not your base URL and the endpoints are disconnected from a live LogisticsOS system.

Curl

curl -X GET \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  '<base URL>/api/v1/Recipients/RecipientDetails?EmpID=LOS1001&ProfileID=1'

Success Response

...

Add a Recipient

Endpoint: POST /api/v1/Recipients/Recipients

For additional endpoint details, including status codes, see full specification. Note: This reference is not your base URL and the endpoints are disconnected from a live LogisticsOS system.

Curl

curl -X POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  -d '{
    "empId": "LOS1001",
    "fullName": "Smith, Janet",
    "preferredName": "Jane",
    "cardID": "3041264",
    "phoneNumber": "111-222-3333",
    "department": "Accounting",
    "building": "Tower 1",
    "floor": "4",
    "room": "409",
    "emailAddress": "jsmith@company.org",
    "download": 2,
    "dynamic": 1,
    "status": 1,
    "profileId": 1
  }' \
  '<base URL>/api/v1/Recipients/Recipients'

Success Response

...

Update a Recipient

Endpoint: PATCH /api/v1/Recipients/Recipients

In the following example, the record's building and floor are being updated to new values and the room value is being cleared. All other fields will retain their existing values.

When updating records, empID and profileID are the only required fields.

For additional endpoint details, including nullable fields and status codes, see full specification. Note: This reference is not your base URL and the endpoints are disconnected from a live LogisticsOS system.

Curl

curl -X PATCH \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  -d '{
    "empId": "LOS1001",
    "building": "Annex 5",
    "floor": "1",
    "room": null,
    "profileId": 1
  }' \
  '<base URL>/api/v1/Recipients/Recipients'

Success Response

...