api/v1/cardfiles/{cardno}/contacts

Path: api/v1/cardfiles/{cardno}/contacts

This API is JSON:API compliant.

This endpoint supports the following methods:
GET POST PATCH DELETE

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 CardFileContact
The identifier is cardno-contno

Attributes

The CardFileContact 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
contNo	integer	✓	The contact number (unique within the card file).
department	string		The contact's department.
details	array of object		The contact's detail entries (phone, mobile, email, etc.). See the details section below.
displayName	string		The contact's display name.
dob	string		The contact's date of birth, as an ISO date.
firstName	string		The contact's first name.
isPrimary	boolean	✓	Whether this is the primary contact for the card file.
jobTitle	string		The contact's job title.
lastName	string		The contact's last name.
middleName	string		The contact's middle name.
title	string		The contact's title (e.g. Mr, Ms).
webAccount	object		The contact's web logon account (the password is write-only and never returned). See the webAccount section below.

details

Attributes of each element in the details array.

Attribute	Type	Description
comments	string	Comments about the contact detail.
type	string	The contact detail type (e.g. Phone, Mobile, Email).
value	string	The contact detail value.

webAccount

Attributes of the webAccount object.

Attribute	Type	Description
enabled	boolean	Flag to indicate if the web logon is enabled. If omitted on creates the account will be enabled.
logonId	string	The logon id for the contact must be unique.
password	string	If not provided Jim2 will automatically generate a password for the contact. Note: Will not be returned in the response if value is null.

Example GET (Return all)

Path: api/v1/cardfiles/10/contacts

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": "10-1",
            "type": "CardFileContact",
            "attributes": {
                "contNo": 1,
                "title": "Mr",
                "firstName": "Contact",
                "middleName": "James",
                "lastName": "One",
                "displayName": "Contact One",
                "jobTitle": "Purchasing Manager",
                "department": "Procurement",
                "dob": "1985-06-15",
                "isPrimary": true,
                "details": [
                    {
                        "type": "Phone",
                        "value": "0413 000 000",
                        "comments": "Direct line"
                    },
                    {
                        "type": "EMail",
                        "value": "contact.one@acme.example",
                        "comments": "Preferred contact method"
                    }
                ],
                "webAccount": {
                    "enabled": true,
                    "logonId": "contact.one@acme.example"
                }
            }
        },
        {
            "id": "10-2",
            "type": "CardFileContact",
            "attributes": {
                "displayName": "Contact Two",
                "isPrimary": false
            }
        }
    ]
}

Example GET (Return specific)

Path: api/v1/cardfiles/10/contacts/10-1

Response:

{
    "data": {
        "id": "10-1",
        "type": "CardFileContact",
        "attributes": {
            "contNo": 1,
            "title": "Mr",
            "firstName": "Contact",
            "middleName": "James",
            "lastName": "One",
            "displayName": "Contact One",
            "jobTitle": "Purchasing Manager",
            "department": "Procurement",
            "dob": "1985-06-15",
            "isPrimary": true,
            "details": [
                {
                    "type": "Phone",
                    "value": "0413 000 000",
                    "comments": "Direct line"
                },
                {
                    "type": "EMail",
                    "value": "contact.one@acme.example",
                    "comments": "Preferred contact method"
                }
            ],
            "webAccount": {
                "enabled": true,
                "logonId": "contact.one@acme.example"
            }
        },
        "links": {
            "self": "/api/v1/cardfiles/10/contacts/10-1"
        }
    }
}

Example POST

Path: api/v1/cardfiles/contacts

Request:

{
    "data": {
        "type": "CardFileContact",
        "attributes": {
            "isPrimary": false,
            "title": "Dr",
            "firstName": "Contact",
            "middleName": "T",
            "lastName": "Three",
            "displayName": "Contact Three",
            "jobTitle": "Support Engineer",
            "department": "Service",
            "dob": "1990-01-31",
            "details": [
                {
                    "type": "EMail",
                    "value": "Contact3@test.com",
                    "comments": "Primary email"
                }
            ],
            "webAccount": {
                "enabled": true,
                "logonId": "Contact3@test.com",
                "password": "ChangeMe123!"
            }
        }
    }
}

Response:

{
    "data": {
        "id": "10-3",
        "type": "CardFileContact",
        "attributes": {
            "contNo": 3,
            "title": "Dr",
            "firstName": "Contact",
            "middleName": "Robert",
            "lastName": "Three",
            "displayName": "Contact Three",
            "jobTitle": "Chief Financial Officer",
            "department": "Finance",
            "dob": "1978-11-02",
            "isPrimary": true,
            "details": [
                {
                    "type": "EMail",
                    "value": "Contact3@test.com",
                    "comments": "Accounts enquiries"
                },
                {
                    "type": "Mobile",
                    "value": "0414 333 333",
                    "comments": "After hours"
                }
            ],
            "webAccount": {
                "enabled": true,
                "logonId": "Contact3@test.com"
            }
        },
        "links": {
            "self": "/api/v1/cardfiles/10/contacts/10-3"
        }
    }
}

Example PATCH

Path: api/v1/cardfiles/10/contacts/10-1

Request:

{
    "data": {
        "id": "10-1",
        "type": "CardFileContact",
        "attributes": {
            "title": "Ms",
            "firstName": "Jane",
            "middleName": "A",
            "lastName": "Smith",
            "displayName": "Jane Smith",
            "jobTitle": "Procurement Manager",
            "department": "Purchasing",
            "dob": "1985-06-15",
            "details": [
                {
                    "type": "EMail",
                    "value": "jane.smith@acme.example",
                    "comments": "Work email"
                }
            ],
            "webAccount": {
                "enabled": true,
                "logonId": "jane.smith",
                "password": "ChangeMe123!"
            }
        }
    }
}

Response:

{
    "data": {
        "id": "10-1",
        "type": "CardFileContact",
        "attributes": {
            "contNo": 1,
            "title": "Mr",
            "firstName": "Contact",
            "middleName": "James",
            "lastName": "One",
            "displayName": "Contact One",
            "jobTitle": "Purchasing Manager",
            "department": "Procurement",
            "dob": "1985-06-15",
            "isPrimary": true,
            "details": [
                {
                    "type": "Phone",
                    "value": "0413 000 000",
                    "comments": "Direct line"
                },
                {
                    "type": "EMail",
                    "value": "contact.one@acme.example",
                    "comments": "Preferred contact method"
                }
            ],
            "webAccount": {
                "enabled": true,
                "logonId": "contact.one@acme.example"
            }
        },
        "links": {
            "self": "/api/v1/cardfiles/10/contacts/10-1"
        }
    }
}