api/v1/projects

Path: api/v1/projects

This API is JSON:API compliant.

This endpoint supports the following methods:
GET POST PATCH

This endpoint requires an OAuth bearer token, and returns errors in a standard shape. See API Conventions for authentication, error responses and paging, which apply to every endpoint.

The resource type for this endpoint is Contract
The identifier is projectno

Relationships

A relationship links this Contract to another resource. By default only the related resource's type and id are returned. Relationships marked Includable can be embedded in the response via the include query parameter (see Includes below). To set or change a relationship, send a resource identifier (type and id) for it. Postable means the relationship can be set when creating the resource (POST); Patchable means it can be changed when updating an existing resource (PATCH). Some relationships are Postable but not Patchable — they can be set at creation but not changed afterwards. A value sent for a relationship that is not Postable/Patchable in that context is not applied.

NotePostable and Patchable describe what the API surface accepts. Whether a particular change is permitted also depends on the resource's current state and your permissions, which Jim2 enforces — a change that is not allowed is rejected with an error response (see the Conventions page).

Relationship	Type	Returns	Includable	Postable	Patchable
accountManager	CardFile	object	✓	✓	✓
asset	Asset	object	✗	✓	✓
billingItem	Item	array	✓	✓	✓
customer	CardFile	object	✓	✓	✓
name	CardFile	object	✓	✓	✓
ship	CardFile	object	✓	✓	✓

Includes

Use the include query parameter to embed Includable relationships in a single response, for example:
GET /api/v1/projects/{projectno}?include=customer,ship,accountManager,name,billingItem

Embedded resources are returned in a top-level included array, not nested inside the relationship. Match each one back to its relationship by type and id.

NoteEach relationship you include embeds its full related resources in the response, so requesting includes — especially several at once, or to-many relationships that return every related row with no paging — can greatly increase the size of the payload. Only request the includes you actually need.

For example, requesting include=customer returns the customer reference under relationships and the full resource in the included array. The reference and the included entry share the same type and id:

		
GET /api/v1/projects/{projectno}?include=customer

{
  "data": {
    "type": "Contract",
    "id": "1001",
    "relationships": {
      "customer": {
        "data": { "type": "CardFile", "id": "2002" }
      }
    }
  },
  "included": [
    {
      "type": "CardFile",
      "id": "2002",
      "attributes": { ... }
    }
  ]
}

If no include is requested, the response has no included key (not an empty array).
The included array is flat and de-duplicated: a resource referenced by two relationships appears once.

Attributes

The Contract resource type attributes are as follows:

Read-only — a tick means the value is set by Jim2 and cannot be changed through the API: it is returned in responses, but any value you send for it in a POST or PATCH is rejected.
Attribute names are case-sensitive and must be sent and read exactly as shown. The API mixes capitalisation styles — some names are PascalCase (e.g. Status, CustRef, DateDue) and others camelCase (e.g. dateIn, priceLevel) — so copy each name verbatim rather than assuming one convention. Filter names (in the filter list on the GET example) may differ from the attribute names.
Monetary and quantity values are decimal numbers whose number of decimal places depends on your Jim2 configuration. They are returned as JSON numbers with their scale preserved. Parse them as decimal / fixed-point values, not floating-point, to preserve precision.

Attribute	Type	Read-only	Description
billingItemDesc	string		The billing item description.
BranchCode	string		The branch code. On update, must match a configured branch. Branches are optional in Jim2 - this is only set when your site is configured to use branches.
companyCode	string		The company code. On update, must match a configured company.
custRef	string		The customer's reference for the project.
dateIn	string		The project start date, as an ISO date.
dateOut	string		The project end date, as an ISO date.
GLDeptCode	string		The GL department code. On update, must match a configured GL department. GL departments are optional in Jim2 - this is only set when your site is configured to use GL departments.
groups	array of object	✓	The groups the project belongs to. See the groups section below.
priority	string		The project's priority.
projectCode	string		The project (contract) code.
projectTypeName	string		The project type name. On update, must match a configured project type.
reqDays	integer		The default number of days until due (required days).
reqHours	integer		The default number of hours until due (required hours).
status	string		The project's status.
SubBranchCode	string		The sub-branch code. On update, must match a configured sub-branch. Sub-branches are optional in Jim2 - this is only set when your site is configured to use sub-branches.

groups

Attributes of each element in the groups array.

Attribute	Type	Description
id	integer	The group's unique identifier.
name	string	The group's name.
type	string	The group's type.

Example GET (Return using filter)

Path: api/v1/projects?filter[isActive]=True&filter[customer.id]=6&filter[master.id]=1111&filter[custRef][-like]CR-2026

Filtering

For more information see Resource Filtering.

Project Filter uses list technology to retreive data. Names should match those on the list screen in Jim List Help.

The following fields can be used to filter by.

Field	Type	Comment
accountManager.id	Int
BranchCode	Text	Branch code
cardGroup	Text	The group that the customer card file linked to the project belongs to
companyCode	Text	Company code
counterName	Text	CounterName on the project meter setup
customer.id	Int
customerPostCode	Text	Delivery Postcode of the customer
custRef	Text
dateIn	DateTime
dateOut	DateTime	Date project was finished
eKMLastContact	DateTime	Projects last contact with EKM. Use equals only. It will get Projects with EKM contact date less than date
financeCardFile.id	Int
financeExpire	DateTime
financeStart	DateTime
financeTerms	Int	Number of months the finance Terms are. Use with -gt and -lt
GLDeptCode	Text	GLDept code
groups	Text	The group the project belongs to
hasUnreadEmail	Bool	Tick to show only projects with unread emails
isActive	Bool
isBillable	Bool	Selects all projects that are billable.
isBillingDue	Bool	Selects all Projects in the state of Billing Due
isBillingReady	Bool	Selects all Projects in the state of Finish
isConsolidated	Bool	if Consolidated is selected on the Vendor tab of a cardfile (Group PO By Project Method), ticking this box will show all projects with Consolidated purchase orders
isFinished	Bool
isHappenEKM	Bool
isRequest	Bool	Has a page request been sent
item.id	Int
itemGroup	Text	The group that the item linked to the project belongs to
itemMake	Text	Item Make that is on the Project
itemModel	Text	Item Model that is on the Project
lastActualRead	DateTime	Projects last read. Use equals only. It will get Projects with last read date less than date
lastBilled	DateTime
master.id	Int	Projects that have this as Master
meterCard	Text	Projects with CardFile on the meter setup
meterStock	Text	Projects with Stock on the meter setup
nameCard	Text	The Name CardFile on the Project
nextBill	DateTime
notes	Text	Text on a note on the project
noteType	Text	Projects with a particular Note Type
originatorCardFile.id	Int
priceLevel	Text	The Contract Price Level of the project
priceRevision	DateTime	Projects with Price Revision. Use equals only. It will get Projects with Price Revision date less than date
priority	Text
project.id	Int
projectType	Text	The Type (Machine, Master etc.)
requestCardFile.id	Int
requestSent	DateTime	Projects with last read request. Use equals only. A date when the last request was sent before this date
serial	Text	Serial Number on the Project
ship.id	Int
shipGroup	Text	The group that the ship card file linked to the project belongs to
shipPostCode	Text	Delivery Postcode of the ship card
shipSuburb	Text	Delivery Suburb of the ship card
sourceName	Text	ObjectSource code
sourceValue	Text
status	Text
SubBranchCode	Text	SubBranch code
suburb	Text	Delivery Suburb of the customer
warrantyIn	DateTime
warrantyOut	DateTime

Response:

This example shows the maximum set of fields the endpoint can return, all populated. A real response only contains the data that applies to that record, so fields that are empty or not relevant are omitted — do not assume every field shown here will be present in every response.

This is a list. To keep the example readable, only the first item below is written out; the later items have been trimmed down in this documentation. In a real response each item comes back with the data applicable to that record (as described above).

Side-loading related resources with the include query parameter is not supported on list endpoints: an include parameter is ignored here and no included section is returned. To retrieve a related resource, request it directly using the id shown in each item's relationships, or use the single-resource (get by id) endpoint, which does support include.

{
  "data": [
    {
      "id": "4",
      "type": "Contract",
      "attributes": {
        "projectCode": "CONTRACT.SUB",
        "priority": "Normal",
        "status": "Booked",
        "custRef": "CR-2026-0041",
        "reqDays": 30,
        "reqHours": 4,
        "dateIn": "2025-10-22",
        "dateOut": "2026-10-21",
        "billingItemDesc": "MultiFunction Centre Type 2",
        "companyCode": "HAPPEN",
        "projectTypeName": "Machine",
        "BranchCode": "SYD",
        "SubBranchCode": "SYD-NORTH",
        "GLDeptCode": "SERVICE",
        "groups": [
          {
            "type": "Region",
            "id": 1,
            "name": "East Coast"
          },
          {
            "type": "Industry",
            "id": 4,
            "name": "Manufacturing"
          }
        ]
      },
      "relationships": {
        "customer": { "data": { "type": "CardFile", "id": "6" } },
        "ship": { "data": { "type": "CardFile", "id": "6" } },
        "billingItem": { "data": { "type": "Item", "id": "6" } },
        "name": { "data": { "type": "CardFile", "id": "16" } },
        "accountManager": { "data": { "type": "CardFile", "id": "16" } },
        "asset": { "data": { "type": "Asset", "id": "1" } }
      },
      "links": {
        "self": "/jim_webapi/api/v1/projects/4"
      }
    },
    {
      "id": "5",
      "type": "Contract",
      "attributes": {
        "projectCode": "CONTRACT.MAINT",
        "status": "In Progress"
      }
    }
  ]
}

Example GET (Return specific)

Path: api/v1/projects/4?include=customer,ship,accountManager,name,billingItem

Response:

{
  "data": {
    "id": "4",
    "type": "Contract",
    "attributes": {
      "projectCode": "CONTRACT.SUB",
      "priority": "Normal",
      "status": "Booked",
      "custRef": "CR-2026-0041",
      "reqDays": 30,
      "reqHours": 4,
      "dateIn": "2025-10-22",
      "dateOut": "2026-10-21",
      "billingItemDesc": "MultiFunction Centre Type 2",
      "companyCode": "HAPPEN",
      "projectTypeName": "Machine",
      "BranchCode": "SYD",
      "SubBranchCode": "SYD-NORTH",
      "GLDeptCode": "SERVICE",
      "groups": [
        {
          "type": "Region",
          "id": 1,
          "name": "East Coast"
        },
        {
          "type": "Industry",
          "id": 4,
          "name": "Manufacturing"
        }
      ]
    },
    "relationships": {
      "customer": { "data": { "type": "CardFile", "id": "6" } },
      "ship": { "data": { "type": "CardFile", "id": "6" } },
      "billingItem": { "data": { "type": "Item", "id": "6" } },
      "name": { "data": { "type": "CardFile", "id": "16" } },
      "accountManager": { "data": { "type": "CardFile", "id": "16" } },
      "asset": { "data": { "type": "Asset", "id": "1" } }
    },
    "links": {
      "self": "/jim_webapi/api/v1/projects/4"
    }
  },
  "included": [
    {
      "type": "CardFile",
      "id": "6",
      "attributes": {
        "cardNo": 6,
        "cardCode": "ACME",
        "contact": "Jane Smith",
        "name": "Acme Corporation Pty Ltd",
        "aBN": "51 824 753 556",
        "aCN": "824 753 556",
        "shipVia": "Courier Express",
        "shipAmount": 15.00,
        "branchCode": "SYD",
        "subBranchCode": "SYD-NORTH",
        "gLDeptCode": "SERVICE",
        "customer": {
          "terms": "30 Days",
          "priceLevel": "Retail",
          "custPONo": "PO-ACME-4471",
          "currencyCode": "AUD",
          "creditHold": "OFF( Auto )",
          "creditLimit": 50000.00,
          "accFeePerc": 1.50,
          "bPayRefNo": "1234567890",
          "backorder": "Allow Backorders",
          "requiredDays": 30,
          "requiredHours": 4,
          "taxPaid": true,
          "taxExclCode": "GST",
          "taxInclCode": "GSTINC",
          "batchInvGroupBy": "Customer",
          "sendStatementVia": "Email",
          "sendInvVia": "Email",
          "groups": [
            { "type": "Region", "id": 1, "name": "East Coast" }
          ]
        },
        "address": {
          "isAddressResidential": false,
          "streetAddress": "12 Industrial Ave",
          "suburb": "Chatswood",
          "state": "NSW",
          "postCode": "2067",
          "country": "Australia"
        },
        "delAddress": {
          "isAddressResidential": false,
          "streetAddress": "12 Industrial Ave",
          "suburb": "Chatswood",
          "state": "NSW",
          "postCode": "2067",
          "country": "Australia"
        }
      },
      "relationships": {
        "contacts": {
          "data": [
            { "type": "CardFileContact", "id": "6-1" }
          ]
        },
        "accountManager": {
          "data": { "type": "CardFile", "id": "7" }
        }
      }
    },
    {
      "type": "CardFile",
      "id": "16",
      "attributes": {
        "cardNo": 16,
        "cardCode": "STAFF.AM",
        "contact": "Alex Manager",
        "name": "Alex Manager",
        "aBN": "",
        "aCN": "",
        "shipVia": "",
        "shipAmount": 0.00,
        "branchCode": "SYD",
        "subBranchCode": "SYD-NORTH",
        "gLDeptCode": "SALES",
        "customer": {
          "terms": "30 Days",
          "priceLevel": "Retail",
          "custPONo": "PO-AM-001",
          "currencyCode": "AUD",
          "creditHold": "OFF( Auto )",
          "creditLimit": 10000.00,
          "accFeePerc": 0.00,
          "bPayRefNo": "9900112233",
          "backorder": "Allow Backorders",
          "requiredDays": 7,
          "requiredHours": 0,
          "taxPaid": false,
          "taxExclCode": "GST",
          "taxInclCode": "GSTINC",
          "batchInvGroupBy": "Customer",
          "sendStatementVia": "Email",
          "sendInvVia": "Email",
          "groups": [
            { "type": "Region", "id": 1, "name": "East Coast" }
          ]
        },
        "address": {
          "isAddressResidential": false,
          "streetAddress": "Level 2, 88 Market Street",
          "suburb": "Sydney",
          "state": "NSW",
          "postCode": "2000",
          "country": "Australia"
        },
        "delAddress": {
          "isAddressResidential": false,
          "streetAddress": "Level 2, 88 Market Street",
          "suburb": "Sydney",
          "state": "NSW",
          "postCode": "2000",
          "country": "Australia"
        }
      },
      "relationships": {
        "contacts": {
          "data": [
            { "type": "CardFileContact", "id": "16-1" }
          ]
        },
        "accountManager": {
          "data": { "type": "CardFile", "id": "7" }
        }
      }
    },
    {
      "type": "Item",
      "id": "6",
      "attributes": {
        "ItemCode": "MFC.TYPE2",
        "Description": "MultiFunction Centre Type 2"
      }
    }
  ]
}

Example POST

Path: api/v1/projects

Request:

{
  "data": {
    "type": "Contract",
    "attributes": {
      "projectCode": "TEST-148079",
      "priority": "High",
      "status": "ACTIVE",
      "custRef": "48777",
      "reqDays": 30,
      "reqHours": 4,
      "dateIn": "2023-10-01",
      "dateOut": "2028-09-30",
      "billingItemDesc": "Master Contract",
      "companyCode": "PERTH",
      "projectTypeName": "Master",
      "BranchCode": "PER",
      "SubBranchCode": "PERHO",
      "GLDeptCode": "SERVICE"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "CardFile",
          "id": "4545"
        }
      },
      "ship": {
        "data": {
          "type": "CardFile",
          "id": "2221"
        }
      },
      "billingItem": {
        "data": {
          "type": "Item",
          "id": "4334"
        }
      },
      "accountManager": {
        "data": {
          "type": "CardFile",
          "id": "114705"
        }
      },
      "name": {
        "data": {
          "type": "CardFile",
          "id": "114705"
        }
      },
      "asset": {
        "data": {
          "type": "Asset",
          "id": "9021"
        }
      }
    }
  }
}

Response:

{
  "data": {
    "id": "148079",
    "type": "Contract",
    "attributes": {
      "projectCode": "TEST-148079",
      "priority": "High",
      "status": "ACTIVE",
      "custRef": "48777",
      "reqDays": 30,
      "reqHours": 4,
      "dateIn": "2023-10-01",
      "dateOut": "2028-09-30",
      "billingItemDesc": "Master Contract",
      "companyCode": "PERTH",
      "projectTypeName": "Master",
      "BranchCode": "PER",
      "SubBranchCode": "PERHO",
      "GLDeptCode": "SERVICE",
      "groups": [
        {
          "type": "Non Report",
          "id": 132,
          "name": "Non Government"
        }
      ]
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "CardFile",
          "id": "4545"
        }
      },
      "ship": {
        "data": {
          "type": "CardFile",
          "id": "2221"
        }
      },
      "billingItem": {
        "data": {
          "type": "Item",
          "id": "4334"
        }
      },
      "accountManager": {
        "data": {
          "type": "CardFile",
          "id": "114705"
        }
      },
      "name": {
        "data": {
          "type": "CardFile",
          "id": "114705"
        }
      },
      "asset": {
        "data": {
          "type": "Asset",
          "id": "1"
        }
      }
    },
    "links": {
      "self": "/jim_webapi_nonmulticompany/api/v1/projects/148079"
    }
  }
}

Example PATCH

Path: api/v1/projects/10

Request:

{
  "data": {
    "id": "148079",
    "type": "Contract",
    "attributes": {
      "projectCode": "TEST-148079",
      "priority": "High",
      "status": "ACTIVE",
      "custRef": "48777",
      "reqDays": 30,
      "reqHours": 4,
      "dateIn": "2023-10-01",
      "dateOut": "2028-09-30",
      "billingItemDesc": "Master Contract",
      "companyCode": "PERTH",
      "projectTypeName": "Master",
      "BranchCode": "PER",
      "SubBranchCode": "PERHO",
      "GLDeptCode": "SERVICE"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "CardFile",
          "id": "4545"
        }
      },
      "ship": {
        "data": {
          "type": "CardFile",
          "id": "2221"
        }
      },
      "billingItem": {
        "data": {
          "type": "Item",
          "id": "4334"
        }
      },
      "accountManager": {
        "data": {
          "type": "CardFile",
          "id": "114705"
        }
      },
      "name": {
        "data": {
          "type": "CardFile",
          "id": "114705"
        }
      },
      "asset": {
        "data": {
          "type": "Asset",
          "id": "9021"
        }
      }
    },
    "links": {
      "self": "/jim_webapi_nonmulticompany/api/v1/projects/148079"
    }
  }
}

Response:

{
  "data": {
    "id": "148079",
    "type": "Contract",
    "attributes": {
      "projectCode": "TEST-148079",
      "priority": "High",
      "status": "ACTIVE",
      "custRef": "48777",
      "reqDays": 30,
      "reqHours": 4,
      "dateIn": "2023-10-01",
      "dateOut": "2028-09-30",
      "billingItemDesc": "Master Contract",
      "companyCode": "PERTH",
      "projectTypeName": "Master",
      "BranchCode": "PER",
      "SubBranchCode": "PERHO",
      "GLDeptCode": "SERVICE",
      "groups": [
        {
          "type": "Non Report",
          "id": 132,
          "name": "Non Government"
        }
      ]
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "CardFile",
          "id": "4545"
        }
      },
      "ship": {
        "data": {
          "type": "CardFile",
          "id": "2221"
        }
      },
      "billingItem": {
        "data": {
          "type": "Item",
          "id": "4334"
        }
      },
      "accountManager": {
        "data": {
          "type": "CardFile",
          "id": "114705"
        }
      },
      "name": {
        "data": {
          "type": "CardFile",
          "id": "114705"
        }
      },
      "asset": {
        "data": {
          "type": "Asset",
          "id": "1"
        }
      }
    },
    "links": {
      "self": "/jim_webapi_nonmulticompany/api/v1/projects/148079"
    }
  }
}