This article lists the ToolWatch API requests for purchase orders: Create, Retrieve, and Retrieve List. Every request needs an authorization token. To get one, see ToolWatch API: Authorization.
Create
Request
URI
https://api.{cluster}.toolwatch.net/purchaseordersHttp Method
POST
Headers
Authorization: {token}
Request Body
Field | Type | Required | Description |
Id | guid | Yes | Purchase order id (guid you generate). |
Number | string | Yes | Purchase order number. Max 15 characters. |
VendorId | guid | Yes | Vendor id. |
ShipToEntityId | guid | Yes | Ship-to entity id. |
OrderedByEntityId | guid | Yes | Ordered-by entity id. |
ShippingMethodId | guid | Yes | Shipping method id. |
OrderedOn | date | Yes | Date the order was placed. |
ExpectedDeliveryOn | date | Yes | Expected delivery date. |
StatusId | integer | Yes | Order status. Allowable values 1-8. |
IsToolWatchBilled | boolean | No | Whether the order is ToolWatch billed. |
RequisitionNumber | string | No | Requisition number. Max 20 characters. |
DocumentNumber | string | No | Document number. Max 25 characters. |
CostCenterId | guid | No | Cost center id. |
CostCodeId | guid | No | Cost code id. |
Response
201 Created
The response header contains the URI for the newly created purchase order.
Location: https://api.{cluster}.toolwatch.net/purchaseorders/{id}400 Bad Request
Triggered when field level validation fails.
Response body will contain validation message
[
{
"PropertyName": "Number",
"Message": "Please provide a purchase order number.",
"AttemptedValue": ""
}
]
Retrieve
Request
URI
https://api.{cluster}.toolwatch.net/purchaseorders/{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. |
Number | string | Purchase order number. |
VendorId | guid | Vendor id. |
ShipToEntityId | guid | Ship-to entity id. |
IsToolWatchBilled | boolean | Whether the order is ToolWatch billed. |
OrderedByEntityId | guid | Ordered-by entity id. |
ShippingMethodId | guid | Shipping method id. |
OrderedOn | date | Date the order was placed. |
ExpectedDeliveryOn | date | Expected delivery date. |
StatusId | integer | Order status. |
RequisitionNumber | string | Requisition number. |
DocumentNumber | string | Document number. |
CostCenterId | guid | Cost center id. |
CostCodeId | guid | Cost code id. |
CollaborateCount | integer | Collaboration message count. |
CollaborateReadMessageCount | integer | Read collaboration message count. |
Example response body:
{
"Id": "{id}",
"Number": "PO-1001",
"VendorId": "849197e3-6cc4-4150-ae71-3f2fc1fbc53d",
"StatusId": 3,
"OrderedOn": "2026-09-10T00:00:00"
}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 purchase order id.Retrieve List
Request
URI
https://api.{cluster}.toolwatch.net/purchaseordersAllowable 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. |
Number | string | Purchase order number. |
VendorId | guid | Vendor id. |
ShipToEntityId | guid | Ship-to entity id. |
IsToolWatchBilled | boolean | Whether the order is ToolWatch billed. |
OrderedByEntityId | guid | Ordered-by entity id. |
ShippingMethodId | guid | Shipping method id. |
OrderedOn | date | Date the order was placed. |
ExpectedDeliveryOn | date | Expected delivery date. |
StatusId | integer | Order status. |
RequisitionNumber | string | Requisition number. |
DocumentNumber | string | Document number. |
CostCenterId | guid | Cost center id. |
CostCodeId | guid | Cost code id. |
CollaborateCount | integer | Collaboration message count. |
CollaborateReadMessageCount | integer | Read collaboration message count. |
Example response body:
[
{
"Id": "849197e3-6cc4-4150-ae71-3f2fc1fbc53d",
"Number": "PO-1001",
"VendorId": "cc09dbb0-6cc4-4150-ae71-3f2fc1fbc53d",
"StatusId": 3,
"OrderedOn": "2026-09-10T00:00:00"
}
]
404 Not Found
Triggered when field parameters in querystring are not allowed.
Response body will contain error message
{"Message":"Criteria is invalid","Type":"Exception"}