Items

This API allows listing, retrieving, creating, updating, and deleting items (products). Items are identified by their UUID.

List Items

GET /item/

List all items.

Sample request:

GET /item/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Accept: application/json
Query Parameters:

  • sortedBy – Available sorting criteria: name

  • name – A filtering value for item name

  • partNumber – A filtering value for partNumber

  • taxable – A filtering value for taxable

  • glAccount – A filtering value for glAccount

  • archived – A filtering value for archived

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count": 100,
  "items": [
    {
      "name": "Heaney Menvier screw",
      "partNumber": "5151191313252",
      "uuid": "003813d3f9164e19bf17d5f67ff4fa12",
      "archived": false,
      "link":
        {
          "rel": "detail",
          "url": "https://api.fieldaware.net/item/003813d3f9164e19bf17d5f67ff4fa12"
        }
    },
    {
      "name": "Beier Apollo drill",
      "partNumber": "8005385953623",
      "uuid": "00ff8f446aba4387b5b570d146ac1457",
      "archived": true,
      "link":
        {
          "rel": "detail",
          "url": "https://api.fieldaware.net/item/00ff8f446aba4387b5b570d146ac1457"
        }
    },
  ],
  "page": 0,
  "pageSize": 2,
  "sortedBy": []
}
Response JSON Object:

  • count (int) – total number of items

  • items (array) – array of JSON Objects - items

  • page (int) – page number

  • pageSize (int) – page size

  • sortedBy (array) –

Sample response:

HTTP/1.1 401 AuthenticationError
Content-Type: application/json

{
  "error": {
    "name": "Error identifier",
    "message": "Error description",
  }
}
Status Codes:

  • 401 Unauthorized – AuthenticationError. The client failed to authenticate, typically because the API token was either invalid or not included in the request.

  • 404 Not Found – NotFoundError. A specified resource does not exist.

  • 400 Bad Request – BadRequest. The payload is syntactically malformed for example, the inputs are not encoded as JSON.

  • 422 Unprocessable Entity – APIValidationError. The query parameters and/or body is not valid for this request. This error captures violation of structural assumptions made on the inputs, as captured by the different schemas that are included in this documentation.

Get Item

GET /item/(item_ref)

Retrieve a given item.

Sample request:

GET /item/003813d3f9164e19bf17d5f67ff4fa12 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "description": "",
  "glAccount": null,
  "markupType": "fixed",
  "markupValue": 52.0,
  "name": "PBeta",
  "partNumber": null,
  "taxable": true,
  "trackOnVan": false,
  "unitCost": 749.99,
  "unitPrice": 801.99,
  "uuid": "85f118098f0c4a0d8d8615a8f709a705",
  "customFields": {},
  "archived": false
}
Response JSON Object:

  • description (string) – Description of the item

  • glAccount (string) – Customer glAccount, string or null if the account is not set

  • markupType (string) – markup type

  • markupValue (number) – markup value

  • partNumber (string) – string or null if the part number is not set

  • name (string) – name of the product/item

  • partNumber – string or null if the part number is not set

  • taxable (bool) – indicates if the product/item is taxable

  • trackOnVan (bool) – track on van TODO: add description

  • unitCost (number) – unit cost

  • unitPrice (number) – price of the product/item unit

  • uuid (string) – UUID number of the product/item

  • customFields (obj) – JSON Obj, custom fields of the item

  • archived (bool) – Archived status of the item

Create Item

POST /item/

Create a new minimal item.

Sample request:

POST /item/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

{
  "name": "Name of the item",
}
Request JSON Object:

  • name (string) – Name of the item (required).

Sample response:

HTTP/1.1 201 NO CONTENT
POST /item/

Create a new item.

Sample request:

POST /item/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

{
  "name": "Drill",
  "description": "Drill",
  "partNumber": "SB-009/23",
  "trackOnVan": false,
  "unitCost": 10.23,
  "unitPrice": 10.23,
  "markupType": "fixed",
  "markupValue": 20.34,
  "taxable": false,
  "glAccount": "acc 009",
  "tax1": {
    "group": "taxGr2",
    "name": "tax-004"
  },
  "tax2": {
    "group": "taxGr1",
    "name": "tax-003"
  },
  "customFields": {
    "85f118098f0c4a0d8d8615a8f709a705": true
  },
}
Request JSON Object:

  • name (string) – Name of the item (required).

  • description (string) – Description of the item.

  • partNumber (string) – Part number of the item.

  • trackOnVan (bool) – Whether the item will be tracked on a van.

  • unitCost (number) – The unit cost of the item.

  • unitPrice (number) – The unit price of the item.

  • markupType (string) – The markup type of the item. One of fixed, percentage

  • markupValue (number) – The markup type of the item.

  • taxable (bool) – Whether the item is taxable.

  • glAccount (string) – General Ledger account of the item.

  • tax1 (obj) – Only applicable when tax system of business is non-US.

  • tax2 (obj) – Only applicable when tax system of business is non-US.

  • customFields (obj) – Mapping of declaration keys to values.

POST /item/

Attempt to create a new item without required parameters to perform calculations.

Sample request:

POST /item/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

{
  "name": "Item 4299045093",
  "description": "Description 4c388c56c2c75e89575e",
  "partNumber": "part: 7bb9c463-f7f6-4858-a108-386e51f66d57",
  "trackOnVan": false,
  "taxable": false,
  "unitCost": 111.52
}
Request JSON Object:

  • name (string) – Name of the item (required).

  • description (string) – Description of the item

  • partNUmber (string) – Part number

  • trackOnVan (boolean) – Indicates if the item is tracked

  • taxable (boolean) – Indicates if the item is taxable

  • unitCost (number) – Cost of the unit item

Sample response:

HTTP/1.1 409 CONFLICT
Content-Type: application/json

{
  "error": {
    "message": "Not enough values for calculation.",
    "name": "ConflictError"
  }
}
Status Codes:
Response JSON Object:

  • error (obj) – JSON object with error message and error name

Update Item

PUT /item/(item_ref)

Update a given item.

Archived items can not be updated. Attempts to update an archived item result in a HTTP 409 Conflict error.

Sample request:

PUT /item/85f118098f0c4a0d8d8615a8f709a705 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json

Request body is the same as Create Item, with all properties being optional.

Sample response:

HTTP/1.1 204 No Content
Status Codes:

Archive Item

PUT /item/(item_ref)

Make a PUT request with data containing only the archived key to archive or unarchive a given item.

Sample request:

PUT /item/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

{
  "archived": true
}

Sample response:

HTTP/1.1 204 No Content
Status Codes:

  • 204 No Content – Indicates the item was archived or unarchived successfully.

Delete Item

DELETE /item/(item_ref)

Delete a given item.

Sample request:

DELETE /item/85f118098f0c4a0d8d8615a8f709a705 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Request Headers:

Sample response:

HTTP/1.1 204 No Content
Status Codes: