This article lists the ToolWatch API requests for entities: Create, Retrieve, Retrieve List, Update, and Delete. Every request needs an authorization token. To get one, see ToolWatch API: Authorization.

Create

Request

URI

https://api.{cluster}.toolwatch.net/entities

Http Method

POST

Headers

Authorization: {token}

Request Body

Field	Type	Required	Description
EntityType	string	Yes	Entity type. L (location) or E (employee).
EntityNumber	string	Yes	Entity number. Max 20 characters.
Description	string	Yes	Entity description. Max 50 characters.
StockpointId	guid	Yes	Stockpoint (stock location) the entity belongs to.
DepartmentId	guid	No	Department id.
SupervisorId	guid	No	Supervisor (entity) id.
Stockpoint	boolean	No	Whether the entity is a stock location.
ParentId	guid	No	Parent entity id. Defaults to the stockpoint id when omitted.
FirstName	string	No	First name.
LastName	string	No	Last name.
BarCode	string	No	Bar code.
Phone	string	No	Primary phone number.
Phone2	string	No	Secondary phone number.
Email	string	No	Email address.
Notes	string	No	Free-form notes.
Address	string	No	Address line 1.
Address2	string	No	Address line 2.
State	string	No	State.
Zip	string	No	Zip / postal code.
City	string	No	City.
Country	string	No	Country.
HireDate	date	No	Hire date.
TerminationDate	date	No	Termination date.
InactiveDate	date	No	Inactive date.
NoXferDateBegin	date	No	No-transfer period start date.
NoXferDateEnd	date	No	No-transfer period end date.
Inactive	boolean	No	Whether the entity is inactive.
Username	string	No	Username.
IsPocketPCUser	boolean	No	Whether the entity is a mobile user.
IsTWUser	boolean	No	Whether the entity is a ToolWatch user.
IsVisible	boolean	No	Whether the entity is visible.
NoXfer	boolean	No	Whether transfers are blocked.
CostCenterId	guid	No	Associated cost center id.
CostCodeId	guid	No	Associated cost code id.
DecommissionDate	date	No	Decommission date.

Response

201 Created

The response header contains the URI for the newly created entity.

Location: https://api.{cluster}.toolwatch.net/entities/{id}

400 Bad Request

Triggered when field level validation fails.

Response body will contain validation message

[
  {
    "PropertyName": "EntityType",
    "Message": "Please provide an entity type of L or E.",
    "AttemptedValue": "X"
  }
]

Retrieve

Request

URI

https://api.{cluster}.toolwatch.net/entities/{id}

Allowable querystring parameters

Parameter	Description
columns	Comma-separated list of properties to return.

Http Method

GET

Headers

Authorization: {token}

Request Body

Not allowed for GET

Response

200 Ok

By default every property is returned. Use the columns querystring parameter to limit the response to specific properties.

Field	Type	Description
Id	guid	Unique identifier.
EntityType	string	Entity type. L (location) or E (employee).
EntityNumber	string	Entity number.
Description	string	Entity description.
OrganizationId	string	Organization the entity belongs to.
Organization	string	Organization name.
DepartmentId	guid	Department id.
SupervisorId	guid	Supervisor (entity) id.
StockpointId	guid	Stockpoint (stock location) id.
Stockpoint	boolean	Whether the entity is a stock location.
ParentId	guid	Parent entity id.
FirstName	string	First name.
LastName	string	Last name.
BarCode	string	Bar code.
Phone	string	Primary phone number.
Phone2	string	Secondary phone number.
Email	string	Email address.
Notes	string	Free-form notes.
Address	string	Address line 1.
Address2	string	Address line 2.
State	string	State.
Zip	string	Zip / postal code.
City	string	City.
Country	string	Country.
HireDate	date	Hire date.
TerminationDate	date	Termination date.
InactiveDate	date	Inactive date.
NoXferDateBegin	date	No-transfer period start date.
NoXferDateEnd	date	No-transfer period end date.
Inactive	boolean	Whether the entity is inactive.
Username	string	Username.
IsPocketPCUser	boolean	Whether the entity is a mobile user.
IsTWUser	boolean	Whether the entity is a ToolWatch user.
IsVisible	boolean	Whether the entity is visible.
NoXfer	boolean	Whether transfers are blocked.
CostCenterNumber	string	Associated cost center number.
CostCenterId	guid	Associated cost center id.
CostCenterDescription	string	Associated cost center description.
CostCodeNumber	string	Associated cost code number.
CostCodeId	guid	Associated cost code id.
CostCodeDescription	string	Associated cost code description.
Deleted	boolean	Whether the entity is deleted.
DecommissionDate	date	Decommission date.

Example response body:

{
  "Id": "52553b4c-ab07-447f-90f0-9e2800bee542",
  "EntityType": "L",
  "EntityNumber": "UPD123",
  "Description": "Updated entity of type L",
  "StockpointId": "f97ffba3-7805-4ffb-9bc5-c18f3cae3aa6",
  "Stockpoint": false,
  "Inactive": false,
  "Deleted": false
}

404 Not Found

Triggered when id parameter is not a valid guid or no matching record was found.

Response body will contain error message

{id} is not a valid entity id.

Retrieve List

Request

URI

https://api.{cluster}.toolwatch.net/entities

Allowable querystring parameters

Parameter	Description
columns	Comma-separated list of properties to return.
entitytype	Filter by entity type (L or E).
isstockpoint	Set to `true` to return only stock locations.
number	Filter by entity number.

Http Method

GET

Headers

Authorization: {token}

Request Body

Not allowed for GET

Response

200 Ok

By default every property is returned. Use the columns querystring parameter to limit the response to specific properties.

Field	Type	Description
Id	guid	Unique identifier.
EntityType	string	Entity type. L (location) or E (employee).
EntityNumber	string	Entity number.
Description	string	Entity description.
OrganizationId	string	Organization the entity belongs to.
Organization	string	Organization name.
DepartmentId	guid	Department id.
SupervisorId	guid	Supervisor (entity) id.
StockpointId	guid	Stockpoint (stock location) id.
Stockpoint	boolean	Whether the entity is a stock location.
ParentId	guid	Parent entity id.
FirstName	string	First name.
LastName	string	Last name.
BarCode	string	Bar code.
Phone	string	Primary phone number.
Phone2	string	Secondary phone number.
Email	string	Email address.
Notes	string	Free-form notes.
Address	string	Address line 1.
Address2	string	Address line 2.
State	string	State.
Zip	string	Zip / postal code.
City	string	City.
Country	string	Country.
HireDate	date	Hire date.
TerminationDate	date	Termination date.
InactiveDate	date	Inactive date.
NoXferDateBegin	date	No-transfer period start date.
NoXferDateEnd	date	No-transfer period end date.
Inactive	boolean	Whether the entity is inactive.
Username	string	Username.
IsPocketPCUser	boolean	Whether the entity is a mobile user.
IsTWUser	boolean	Whether the entity is a ToolWatch user.
IsVisible	boolean	Whether the entity is visible.
NoXfer	boolean	Whether transfers are blocked.
CostCenterNumber	string	Associated cost center number.
CostCenterId	guid	Associated cost center id.
CostCenterDescription	string	Associated cost center description.
CostCodeNumber	string	Associated cost code number.
CostCodeId	guid	Associated cost code id.
CostCodeDescription	string	Associated cost code description.
Deleted	boolean	Whether the entity is deleted.
DecommissionDate	date	Decommission date.

Example response body:

[
  {
    "Id": "52553b4c-ab07-447f-90f0-9e2800bee542",
    "EntityType": "L",
    "EntityNumber": "UPD123",
    "Description": "Updated entity of type L",
    "StockpointId": "f97ffba3-7805-4ffb-9bc5-c18f3cae3aa6",
    "Stockpoint": false,
    "Inactive": false,
    "Deleted": false
  },
  {
    "Id": "cc09dbb0-6cc4-4150-ae71-3f2fc1fbc53d",
    "EntityType": "E",
    "EntityNumber": "EMP456",
    "Description": "Employee entity of type E",
    "StockpointId": "f97ffba3-7805-4ffb-9bc5-c18f3cae3aa6",
    "Stockpoint": false,
    "Inactive": false,
    "Deleted": false
  }
]

404 Not Found

Triggered when field parameters in querystring are not allowed.

Response body will contain error message

{"Message":"Criteria is invalid","Type":"Exception"}

Update

Request

URI

https://api.{cluster}.toolwatch.net/entities/{id}

Http Method

PUT

Headers

Authorization: {token}

Request Body

Supply the model completely. Any property that is omitted is overwritten with its default value.

Field	Type	Required	Description
Id	guid	Yes	Unique identifier of the entity to update.
EntityType	string	Yes	Entity type. L (location) or E (employee).
EntityNumber	string	Yes	Entity number. Max 20 characters.
Description	string	Yes	Entity description. Max 50 characters.
StockpointId	guid	Yes	Stockpoint (stock location) the entity belongs to.
DepartmentId	guid	No	Department id.
SupervisorId	guid	No	Supervisor (entity) id.
Stockpoint	boolean	No	Whether the entity is a stock location.
ParentId	guid	No	Parent entity id. Defaults to the stockpoint id when omitted.
FirstName	string	No	First name.
LastName	string	No	Last name.
BarCode	string	No	Bar code.
Phone	string	No	Primary phone number.
Phone2	string	No	Secondary phone number.
Email	string	No	Email address.
Notes	string	No	Free-form notes.
Address	string	No	Address line 1.
Address2	string	No	Address line 2.
State	string	No	State.
Zip	string	No	Zip / postal code.
City	string	No	City.
Country	string	No	Country.
HireDate	date	No	Hire date.
TerminationDate	date	No	Termination date.
InactiveDate	date	No	Inactive date.
NoXferDateBegin	date	No	No-transfer period start date.
NoXferDateEnd	date	No	No-transfer period end date.
Inactive	boolean	No	Whether the entity is inactive.
Username	string	No	Username.
IsPocketPCUser	boolean	No	Whether the entity is a mobile user.
IsTWUser	boolean	No	Whether the entity is a ToolWatch user.
IsVisible	boolean	No	Whether the entity is visible.
NoXfer	boolean	No	Whether transfers are blocked.
CostCenterId	guid	No	Associated cost center id.
CostCodeId	guid	No	Associated cost code id.
DecommissionDate	date	No	Decommission date.
Deleted	boolean	No	Whether the entity is deleted.

Response

200 Ok

400 Bad Request

Triggered when field level validation fails.

Response body will contain validation message

[
  {
    "PropertyName": "EntityType",
    "Message": "Please provide an entity type of L or E.",
    "AttemptedValue": "X"
  }
]

404 Not Found

Triggered when id parameter is not a valid guid or no matching record was found.

Response body will contain error message

{id} is not a valid entity id.

Delete

Request

URI

https://api.{cluster}.toolwatch.net/entities/{id}

Http Method

DELETE

Headers

Authorization: {token}

Request Body

Not allowed for DELETE

Response

200 Ok

404 Not Found

Triggered when id parameter is not a valid guid or no matching record was found.

Response body will contain error message

{id} is not a valid entity id.

ToolWatch API: Entities

Create

Request

Response

Retrieve

Request

Response

Retrieve List

Request

Response

Update

Request

Response

Delete

Request

Response

Related Articles