Bill Of Materials Item

Bill of Materials Items, are the individual items from on a Bill Of Materials.

Schema

`BillOfMaterialsItem`

Name	Type	Description	Example
id	`ID`	Unique BOM item identifier	`"ckmnpybisiy5x08abky4g2d1f"`
createdAt	`DateTime`	When this BOM item was created	`"2021-03-24 17:26:46.983Z"`
updatedAt	`DateTime`	When this BOM item was updated	`"2021-03-24 17:26:46.983Z"`
catalogId	`ID?`	ID of catalog item this BOM item represents	`"ckmnpybisiy5x08abky4g2dog"`
description	`string`		`"Safety Goggles"`
estimatedQuantity	`number`	Estimated quantity of the item	`5`
mpn	`string?`	Manufacturer part number	`"BR115"`
unitOfMeasure	`string?`	Unit of measure	`"EA"`
unitPrice	`decimal?`	Estimated unit price for this BOM item	`12.34`
upc	`string?`	Universal product code	`"012312312340"`
workBreakdownStructureValues	`JSON`	Other content associated with this BOM item in key-value pairs. See more info below	`[{ "structureType": "Phase code", "value": "12" }]`

`workBreakdownStructureValues`

Work Breakdown Structures are key/value pairs indicating how this item fits into your project's workflow. While the structureType can be any string, we support the following Enriched Structure Type Names:

'Cost Code'
'Floor'
'Phase'
'Phase Code'
'Section'
'System'

REST Endpoints

GET `/billOfMaterials/:billOfMaterialsId/items`

Read all billOfMaterialsItems from a parent billOfMaterials, with pagination and filtering.

Parameters

Accepts all standard pagination parameters.

Name	Type	Description	Example
billOfMaterialsId	`ID`	Unique BOM identifier	`"ckmnpybisiy5x08abky4g2d1f"`

Allowed orderBy fields: createdAt, description, estimatedQuantity, id, unitPrice, updatedAt.

Allowed filter fields: createdAt, description, estimatedQuantity, id, unitPrice, updatedAt.

Response

A list of BillOfMaterialsItem objects.

Example Request

GET https://api.kojo.tech/billOfMaterials/ckyd9f1jn4332914x62igytcx/items?limit=3&orderBy=estimatedQuantity

Example Response

[
  {
    "id": "ckmnpybisiy5x08abky4g2d1f",
    "description": "EMT Conduit",
    "estimatedQuantity": 50
  },
  {
    "id": "ckmnpybi7ag5x08abky4g2d1f",
    "description": "Eaton Breaker",
    "estimatedQuantity": 100
  }
  {
    "id": "ckmnpybi7ag5x08abky4g2d1f",
    "description": "4 Sq Box",
    "estimatedQuantity": 200
  }
]

POST `/billOfMaterials/:billOfMaterialsId/items`

Creates new Bill Of Materials Items, and any associated BomWorkBreakdownStructureValue against a Bill of Materials.

Parameters

list of billOfMaterialsItems, see schema below:

BillOfMaterialsItemInput

Name	Type	Description	Example
catalogId	`ID?`	ID of Kojo catalog item	`"ckmnpybisiy5x08abky4g2dog"`
description	`string`	Description of item	`"Safety Goggles"`
estimatedQuantity	`number`	estimated quantity of the item	`5`
mpn	`string`?	Manufacturer Part Number	`"BR115"`
unitOfMeasure?	`string`?	Unit of Measure (defaults to EA if not provided)	`"EA"`
unitPrice	`decimal`?	estimated unit price for this BOM item	`12.34`
upc	`string`?	universal product code	`"012312312340"`
workBreakdownStructureValues	`JSON`	see WBS Values (name/value pairs)	`[{ "structureType": "Phase", "value": "12" }]`

Response

Returns the newly-created BOM items

Example Request

  POST https://api.kojo.tech/billOfMaterials/ckyd9f1jn4332914x62igytcx/items
{
  "billOfMaterialsItems": [{
    "description": "3/4\" EMT",
    "estimatedQuantity": 5,
    "workBreakdownStructureValues": [
      { "structureType": "Phase", "value": "12" },
      { "structureType": "Floor", "value": "2nd" },
      { "structureType": "System", "value": "Fire Alarm" }
    ]
  }]
}

Example Response

[{
  "id": "ckyd9f1jn4332914x62igycat",
  "createdAt": "2022-01-13T17:42:40.019Z",
  "updatedAt": "2022-01-13T17:42:40.019Z",
  "description": "3/4\" EMT",
  "estimatedQuantity": 5,
  "workBreakdownStructureValues": [
    { "structureType": "Phase", "value": "12" },
    { "structureType": "Floor", "value": "2nd" },
    { "structureType": "System", "value": "Fire Alarm" }
  ]
}]

PATCH `/billOfMaterialsItem/:billOfMaterialsItemId`

Updates fields to a specific BillOfMaterialsItem, and adds any associated BomWorkBreakdownStructureValues.

Parameters

Name	Type	Description	Example
input	`BillOfMaterialsItemInput`	BOM item data	see schema below

BillOfMaterialsItemInput

Name	Type	Description	Example
catalogId	`ID?`	ID of Kojo catalog item	`"ckmnpybisiy5x08abky4g2dog"`
description	`string`	Description of Item	`"Safety Goggles"`
estimatedQuantity	`number`	estimated quantity of the item	`5`
mpn	`string`?	Manufacturer part number	`"BR115"`
unitOfMeasure?	`string`?	Unit of Measure	`"EA"`
unitPrice	`decimal`?	estimated unit price for this BOM item	`12.34`
upc	`string`?	universal product code	`"012312312340"`
workBreakdownStructureValues	`JSON`	Any wbsValues input will be additive (must explicitly set WBS values to null if wanting to remove them)	`[{ "structureType": "Phase", "value": "12" }]`

Response

Returns the newly-updated BOM item

Errors

Status	Description
`400`	A field failed validation. The response names the field and the rule, for example `estimatedQuantity must not have any decimal places`. See Field rules
`404`	`Bill of Materials Item not found` — the item does not exist, has been deleted, or belongs to another organization. Kojo does not distinguish these cases

Field rules

These apply to both PATCH endpoints.

Field	Rule
`estimatedQuantity`	Must be a number, zero or greater, and a whole number. Contact Kojo if your organization needs fractional quantities
`unitPrice`	Must be a number, zero or greater
`description`	Cannot be the literal string `"null"`

Example Request

PATCH https://api.kojo.tech/billOfMaterialsItem/clkwzli9w0005wsu931nregy4
{
  "input": {
    "description": "Updated EMT",
    "estimatedQuantity": 5,
    "workBreakdownStructureValues": [
      { "structureType": "Phase", "value": "12" },
    ]
  }
}

Example Response

{
  "id": "clkwzli9w0005wsu931nregy4",
  "createdAt": "2022-01-13T17:42:40.019Z",
  "updatedAt": "2022-01-13T17:42:40.019Z",
  "description": "Updated EMT",
  "estimatedQuantity": 5,
  "workBreakdownStructureValues": [
    { "structureType": "Phase", "value": "12" }, // newly added 
    { "structureType": "Floor", "value": "2nd" }, // existing
  ]
}

DELETE `/billOfMaterialsItem/:billOfMaterialsItemId`

Deletes a Bill Of Materials Item and ensures that all associated entities WBS values are also deleted

Parameters

Name	Type	Description	Example
billOfMaterialsItemId	`ID`	Unique BOM identifier	"ckmnpybisiy5x08abky4g2d1f"

Response

Returns the deleted BOM item

Example Mutation

DELETE https://api.kojo.tech/billOfMaterialsItem/clkwzli9w0005wsu931nregy4

Example Response

{
  "id": "ckyd9f1jn4332914x62igy1oni",
  "createdAt": "2022-01-13T17:42:40.019Z",
  "updatedAt": "2022-01-13T17:42:40.019Z",
  "description": "Deleted EMT",
  "estimatedQuantity": 5,
  "workBreakdownStructureValues": [
    { "structureType": "Phase", "value": "12" }, // newly added 
    { "structureType": "Floor", "value": "2nd" }, // existing
  ]
}

PATCH `/billOfMaterialsItems`

Updates fields for multiple BillOfMaterialsItems, and adds any associated BomWorkBreakdownStructureValues.

caution

A maximum of a 1000 items can be updated per request.

caution

Duplicated item IDs are not accepted.

Parameters

Name	Type	Description	Example
inputs	`BillOfMaterialsItemInputs[]`	BOM items data list. Max length: 1000	see schema below

BillOfMaterialsItemInputs

Name	Type	Description	Example
billOfMaterialsItemId	`ID`	Unique BOM identifier	`"ckmnpybisiy5x08abky4g2d1f"`
input	`BillOfMaterialsItemInput`	BOM item data	see schema below

BillOfMaterialsItemInput

Name	Type	Description	Example
catalogId	`ID?`	ID of Kojo catalog item	`"ckmnpybisiy5x08abky4g2dog"`
description	`string`	Item Description	`"Safety Goggles"`
estimatedQuantity	`number`	estimated quantity of the item	`5`
mpn	`string`?	Manufacturer Part Number	`"BR115"`
unitOfMeasure?	`string`?	Unit of Measure	`"EA"`
unitPrice	`decimal`?	estimated unit price for this BOM item	`12.34`
upc	`string`?	universal product code	`"012312312340"`
workBreakdownStructureValues	`JSON`	Any wbsValues input will be additive (must explicitly set WBS values to null if wanting to remove them)	`[{ "structureType": "Phase", "value": "12" }]`

Response

Returns a list of all updated BOM items.

Example Request

PATCH https://api.kojo.tech/billOfMaterialsItems
{
  "inputs": [
    {
      "billOfMaterialsItemId": "ckyd9f1jn4332914x62igy1oni",
      "input": {
        "description": "Updated EMT",
        "estimatedQuantity": 5,
        "workBreakdownStructureValues": [
          {
            "structureType": "Phase",
            "value": "12"
          }
        ]
      }
    }
  ]
}

Example Response

{
  "id": "clkwzli9w0005wsu931nregy4",
  "createdAt": "2022-01-13T17:42:40.019Z",
  "updatedAt": "2022-01-13T17:42:40.019Z",
  "description": "Updated EMT",
  "estimatedQuantity": 5,
  "workBreakdownStructureValues": [
    { "structureType": "Phase", "value": "12" }, // newly added 
    { "structureType": "Floor", "value": "2nd" }, // existing
  ]
}

Errors

The request is one transaction: if any item is rejected, none of the items in that request are saved. Fix every reported item and resubmit the whole request.

Every rejected item is reported in a single response, one per line, prefixed with its zero-based position in inputs:

{
  "errors": [
    {
      "message": "Position 0: Bill of Materials Item not found\nPosition 2: unitPrice cannot be less than zero"
    }
  ]
}

Status	Description
`400`	One or more items were rejected. The message lists every one. Field rules are the same as the single-item endpoint — see Field rules
`400`	`Invalid input, list cannot be empty`, `Invalid input, list cannot be greater than 1000`, or a duplicate `billOfMaterialsItemId`. These reject the request before any item is examined

Schema​