Path: api/v1/cardfiles
This API is JSON:API compliant.
This endpoint supports the following methods:
GET 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 CardFile
The identifier is cardno
Relationships
A relationship links this CardFile 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.
| Relationship | Type | Returns | Includable | Postable | Patchable |
|---|---|---|---|---|---|
| accountManager | CardFile | object | ✓ | ✗ | ✗ |
| contacts | CardFileContact | object | ✗ | ✗ | ✗ |
| parent | CardFile | object | ✓ | ✗ | ✗ |
Includes
Use the include query parameter to embed Includable relationships in a single response, for example:GET /api/v1/cardfiles/{cardno}?include=accountManager,parent
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.
For example, requesting include=accountManager returns the accountManager 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/cardfiles/{cardno}?include=accountManager
{
"data": {
"type": "CardFile",
"id": "1001",
"relationships": {
"accountManager": {
"data": { "type": "CardFile", "id": "2002" }
}
}
},
"included": [
{
"type": "CardFile",
"id": "2002",
"attributes": { ... }
}
]
}
Attributes
The CardFile resource type attributes are as follows:
| Attribute | Type | Read-only | Description |
|---|---|---|---|
| aBN | string | ✓ | The Australian Business Number (ABN). |
| aCN | string | ✓ | The Australian Company Number (ACN). |
| address | object | The card's main (billing) address. See the address section below. |
|
| branchCode | string | ✓ | The branch code. Branches are optional in Jim2 - this is only set when your site is configured to use branches. |
| cardCode | string | ✓ | The card code. |
| cardNo | integer | ✓ | The card file number (unique identifier for the card). |
| contact | string | ✓ | The primary contact name on the card. |
| customer | object | ✓ | Customer (debtor) account settings held against the card. See the customer section below. |
| delAddress | object | The card's delivery address. See the delAddress section below. |
|
| gLDeptCode | string | ✓ | The GL department code. GL departments are optional in Jim2 - this is only set when your site is configured to use GL departments. |
| name | string | The card file name. | |
| shipAmount | number | ✓ | The customer's default freight amount. |
| shipVia | string | ✓ | The customer's default ship-via (carrier/method). |
| subBranchCode | string | ✓ | The sub-branch code. Sub-branches are optional in Jim2 - this is only set when your site is configured to use sub-branches. |
Attributes of the address object.
| Attribute | Type | Read-only | Description |
|---|---|---|---|
| country | string | The country. | |
| isAddressResidential | boolean | Whether the address is residential. | |
| postCode | string | The post code. | |
| state | string | The state. | |
| streetAddress | string | The street address. | |
| suburb | string | The suburb. |
Attributes of the customer object.
| Attribute | Type | Read-only | Description |
|---|---|---|---|
| accFeePerc | number | ✓ | The customer's account fee percentage. |
| backorder | string | ✓ | The customer's backorder preference: Allow Backorders / No Backorders (Supply Available) / No Part Ship. |
| batchInvGroupBy | string | ✓ | How batch invoices are grouped for the customer: Customer / Ship / Project / Master Project / Don't Group / Customer Ref. |
| bPayRefNo | string | ✓ | The customer's BPay reference number. |
| creditHold | string | ✓ | The customer's credit-hold state, e.g. OFF( Auto ) / ON( Auto ) / ON( Manual ). |
| creditLimit | number | ✓ | The customer's credit limit. |
| currencyCode | string | ✓ | The customer's currency code. |
| custPONo | string | ✓ | The customer's standing purchase-order number. |
| groups | array of object | ✓ | The groups the card belongs to. See the customer.groups section below. |
| priceLevel | string | ✓ | The customer's price level description. |
| requiredDays | integer | ✓ | The default number of days until due for the customer. |
| requiredHours | integer | ✓ | The default number of hours until due for the customer. |
| sendInvVia | string | ✓ | How invoices are sent to the customer: Print / Fax / Email / Email & Print / Don't send. |
| sendStatementVia | string | ✓ | How statements are sent to the customer: Print / Fax / Email / Email & Print / Don't send. |
| taxExclCode | string | ✓ | The tax code for tax-exclusive (wholesale) sales. |
| taxInclCode | string | ✓ | The tax code for tax-inclusive (retail) sales. |
| taxPaid | boolean | ✓ | Whether the customer pays tax. |
| terms | string | ✓ | The customer's payment terms code. |
Attributes of the delAddress object.
| Attribute | Type | Read-only | Description |
|---|---|---|---|
| country | string | The country. | |
| isAddressResidential | boolean | Whether the address is residential. | |
| postCode | string | The post code. | |
| state | string | The state. | |
| streetAddress | string | The street address. | |
| suburb | string | The suburb. |
Attributes of each element in the customer.groups array.
| Attribute | Type | Read-only | Description |
|---|---|---|---|
| id | integer | The group's unique identifier. | |
| name | string | The group's name. | |
| type | string | The group's type. |
Path: api/v1/cardfiles?filter[isCustActive]=True&filter[cardCode][-like]AC For more information see Resource Filtering. CardFile Filter uses list technology to retreive data. Names should match those on the list screen in Jim List Help. 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.
Example GET (Return using filter)
Filtering
Field Type Comment
aBN Text
accountManager.id Int
aCN Text
addressCountry Text
addressPostCode Text
addressState Text
addressStreetAddress Text
addressSuburb Text
branchCode Text Branch code
cardCode Text
companyCode Text Company code
contact Text
contactType Text
custType Text CustType code
delAddressCountry Text
delAddressPostCode Text
delAddressState Text
delAddressStreetAddress Text
delAddressSuburb Text
department Text
displayName Text
firstName Text
gLDeptCode Text GLDept code
groups Text
hasWebLogon Bool
isCustActive Bool
isCustomer Bool
isPersonal Bool
isShip Bool
isShipActive Bool
isUser Bool
isUserActive Bool
isVendor Bool
isVendorActive Bool
jobTitle Text
lastModified DateTime
lastName Text
name Text
parent.id Int
sourceName Text ObjectSource code
sourceValue Text
subBranchCode Text SubBranch code
typeValue Text
userGroups Text
userInitials Text
webLogon Text
{
"data": [
{
"id": "10",
"type": "CardFile",
"attributes": {
"cardNo": 10,
"cardCode": "ACME",
"contact": "Jane Smith",
"name": "Acme Corporation Pty Ltd",
"aBN": "53 004 085 616",
"aCN": "004 085 616",
"shipVia": "Courier Express",
"shipAmount": 25.00,
"branchCode": "SYD",
"subBranchCode": "SYD-NORTH",
"gLDeptCode": "SALES",
"customer": {
"terms": "30 Days",
"priceLevel": "Retail",
"custPONo": "PO-44821",
"currencyCode": "AUD",
"creditHold": "OFF( Auto )",
"creditLimit": 50000.00,
"accFeePerc": 2.50,
"bPayRefNo": "1234567890",
"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": "12 Industrial Ave",
"suburb": "Chatswood",
"state": "NSW",
"postCode": "2067",
"country": "Australia"
},
"delAddress": {
"isAddressResidential": false,
"streetAddress": "14 Industrial Ave",
"suburb": "Chatswood",
"state": "NSW",
"postCode": "2067",
"country": "Australia"
}
},
"relationships": {
"contacts": {
"data": [
{ "type": "CardFileContact", "id": "10-1" },
{ "type": "CardFileContact", "id": "10-2" }
]
},
"accountManager": {
"data": { "type": "CardFile", "id": "16" }
},
"parent": {
"data": { "type": "CardFile", "id": "2" }
}
},
"links": {
"self": "/api/v1/cardfiles/10"
}
},
{
"id": "11",
"type": "CardFile",
"attributes": {
"cardCode": "RIVERSIDE",
"name": "Riverside Manufacturing Co"
}
}
]
}
Path: api/v1/cardfiles/10?include=accountManager,parent 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.
Example GET (Return specific)
{
"data": {
"id": "10",
"type": "CardFile",
"attributes": {
"cardNo": 10,
"cardCode": "ACME",
"contact": "Jane Smith",
"name": "Acme Corporation Pty Ltd",
"aBN": "53 004 085 616",
"aCN": "004 085 616",
"shipVia": "Courier Express",
"shipAmount": 25.00,
"branchCode": "SYD",
"subBranchCode": "SYD-NORTH",
"gLDeptCode": "SALES",
"customer": {
"terms": "30 Days",
"priceLevel": "Retail",
"custPONo": "PO-44821",
"currencyCode": "AUD",
"creditHold": "OFF( Auto )",
"creditLimit": 50000.00,
"accFeePerc": 2.50,
"bPayRefNo": "1234567890",
"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"
},
{
"type": "Industry",
"id": 4,
"name": "Manufacturing"
}
]
},
"address": {
"isAddressResidential": false,
"streetAddress": "12 Industrial Ave",
"suburb": "Chatswood",
"state": "NSW",
"postCode": "2067",
"country": "Australia"
},
"delAddress": {
"isAddressResidential": false,
"streetAddress": "14 Industrial Ave",
"suburb": "Chatswood",
"state": "NSW",
"postCode": "2067",
"country": "Australia"
}
},
"relationships": {
"contacts": {
"data": [
{ "type": "CardFileContact", "id": "10-1" },
{ "type": "CardFileContact", "id": "10-2" }
]
},
"accountManager": {
"data": { "type": "CardFile", "id": "16" }
},
"parent": {
"data": { "type": "CardFile", "id": "2" }
}
},
"links": {
"self": "/api/v1/cardfiles/10"
}
},
"included": [
{
"type": "CardFile",
"id": "16",
"attributes": {
"cardNo": 16,
"cardCode": "STAFF.AM",
"contact": "Alex Manager",
"name": "Alex Manager",
"aBN": "68 987 654 321",
"aCN": "987 654 321",
"shipVia": "Courier Express",
"shipAmount": 15.00,
"branchCode": "SYD",
"subBranchCode": "SYD-NORTH",
"gLDeptCode": "SALES",
"customer": {
"terms": "30 Days",
"priceLevel": "Staff",
"custPONo": "PO-STAFF-01",
"currencyCode": "AUD",
"creditHold": "OFF( Auto )",
"creditLimit": 10000.00,
"accFeePerc": 1.50,
"bPayRefNo": "9988776655",
"backorder": "Allow Backorders",
"requiredDays": 14,
"requiredHours": 0,
"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": "16-1" }
]
},
"accountManager": {
"data": { "type": "CardFile", "id": "16" }
},
"parent": {
"data": { "type": "CardFile", "id": "2" }
}
}
},
{
"type": "CardFile",
"id": "2",
"attributes": {
"cardNo": 2,
"cardCode": "ACME.GROUP",
"contact": "Head Office",
"name": "Acme Group Holdings Pty Ltd",
"aBN": "11 222 333 444",
"aCN": "222 333 444",
"shipVia": "Own Truck",
"shipAmount": 40.00,
"branchCode": "SYD",
"subBranchCode": "SYD-NORTH",
"gLDeptCode": "SALES",
"customer": {
"terms": "30 Days",
"priceLevel": "Retail",
"custPONo": "PO-GROUP-2024",
"currencyCode": "AUD",
"creditHold": "OFF( Auto )",
"creditLimit": 100000.00,
"accFeePerc": 2.00,
"bPayRefNo": "1122334455",
"backorder": "Allow Backorders",
"requiredDays": 30,
"requiredHours": 0,
"taxPaid": true,
"taxExclCode": "GST",
"taxInclCode": "GSTINC",
"batchInvGroupBy": "Master Project",
"sendStatementVia": "Email & Print",
"sendInvVia": "Email & Print",
"groups": [
{
"type": "Region",
"id": 1,
"name": "East Coast"
},
{
"type": "Industry",
"id": 4,
"name": "Manufacturing"
}
]
},
"address": {
"isAddressResidential": false,
"streetAddress": "1 Corporate Drive",
"suburb": "North Sydney",
"state": "NSW",
"postCode": "2060",
"country": "Australia"
},
"delAddress": {
"isAddressResidential": false,
"streetAddress": "1 Corporate Drive",
"suburb": "North Sydney",
"state": "NSW",
"postCode": "2060",
"country": "Australia"
}
},
"relationships": {
"contacts": {
"data": [
{ "type": "CardFileContact", "id": "2-1" }
]
},
"accountManager": {
"data": { "type": "CardFile", "id": "16" }
},
"parent": {
"data": { "type": "CardFile", "id": "2" }
}
}
}
]
}
Path: api/v1/cardfiles/10 Request: 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.
Example PATCH
{
"data": {
"type": "CardFile",
"id": "10",
"attributes": {
"name": "Acme Corporation Pty Ltd",
"address": {
"streetAddress": "street line 1\r\nstreet line 2",
"postCode": "9876",
"state": "STA",
"suburb": "the burbs",
"country": "Australia"
},
"delAddress": {
"streetAddress": "del street line 1\r\nstreet line 2",
"postCode": "8765",
"state": "DEL",
"suburb": "del the burbs",
"country": "Australia"
}
}
}
}
{
"data": {
"id": "10",
"type": "CardFile",
"attributes": {
"cardNo": 10,
"cardCode": "ACME",
"contact": "Jane Smith",
"name": "Acme Corporation Pty Ltd",
"aBN": "53 004 085 616",
"aCN": "004 085 616",
"shipVia": "Courier Express",
"shipAmount": 25.00,
"branchCode": "SYD",
"subBranchCode": "SYD-NORTH",
"gLDeptCode": "SALES",
"customer": {
"terms": "30 Days",
"priceLevel": "Retail",
"custPONo": "PO-44821",
"currencyCode": "AUD",
"creditHold": "OFF( Auto )",
"creditLimit": 50000.00,
"accFeePerc": 2.50,
"bPayRefNo": "1234567890",
"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"
},
{
"type": "Industry",
"id": 4,
"name": "Manufacturing"
}
]
},
"address": {
"isAddressResidential": false,
"streetAddress": "street line 1\r\nstreet line 2",
"suburb": "the burbs",
"state": "STA",
"postCode": "9876",
"country": "Australia"
},
"delAddress": {
"isAddressResidential": false,
"streetAddress": "del street line 1\r\nstreet line 2",
"suburb": "del the burbs",
"state": "DEL",
"postCode": "8765",
"country": "Australia"
}
},
"relationships": {
"contacts": {
"data": [
{ "type": "CardFileContact", "id": "10-1" },
{ "type": "CardFileContact", "id": "10-2" }
]
},
"accountManager": {
"data": { "type": "CardFile", "id": "16" }
},
"parent": {
"data": { "type": "CardFile", "id": "2" }
}
},
"links": {
"self": "/api/v1/cardfiles/10"
}
}
}