API – Read a Record

action – read

This action reads the details of a single record. Optionally include a list of the specific methods to be returned, and/or any calculations; or if no specific methods are requested, the response will include all the information about the record that would be displayed on a standard information page, including lists of steps, notes, files

The record information is returned in record, and always includes, at minimum, the following – recordurl, recordid, recordtype, name

Read Standard Fields

Specify a Single Record and include in values a list of the field names to be returned. The values of each of the specified fields are included in the values response within record

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "read", "recordtype": "person", "recordid": 12345, "values": [ "FirstName", "LastName" ] }

Sample Response

{ "success": true, "record": { "recordurl": "person/12345", "recordid": 12345, "recordtype": "person", "name": "John Smith", "values": { "FirstName": "John", "LastName": "Smith" } } }

Evaluate a Calculation

You can include one or more calculations that should be evaluated against the record. The response to each calculation will be returned in the key name that you provide in the values array.

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "read", "recordtype": "person", "recordid": 12345, "values": [ "FirstName", "LastName", "MyCalc": "left(FirstName,1)+' '+LastName" ] }

Sample Response

{ "success": true, "record": { "recordurl": "person/12345", "recordid": 12345, "recordtype": "person", "name": "John Smith", "values": { "FirstName": "John", "LastName": "Smith", "MyCalc": "J Smith" } } }

Evaluate a Template

Any of the values requested can be specified as a template which will be evaluated against the record. To specify a template, pass the value request as an array with a single element key template and the template string as its value.

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "read", "recordtype": "person", "recordid": 12345, "values": [ "FirstName", "LastName", "MyTemplate": { "template": "My name is {FirstName}" } ] }

Sample Response

{ "success": true, "record": { "recordurl": "person/12345", "recordid": 12345, "recordtype": "person", "name": "John Smith", "values": { "FirstName": "John", "LastName": "Smith", "MyTemplate": "My name is John" } } }

Read a Sub-list

If you include the field name of a sub-list as one of the values, the record list will be returned in that values response.

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "read", "recordtype": "organisation", "recordid": 56789, "values": [ "Name", "People" ] }

Sample Response

{ "success": true, "record": { "recordurl": "organisation/56789", "recordid": 56789, "recordtype": "organisation", "name": "Smith & Sons", "values": { "Name": "Smith & Sons", "People": { "recordtype": "person", "count": 2, "total": 2, "records": [ { "recordurl": "person/12345", "recordid": 12345, "recordtype": "person", "name": "John Smith" }, { "recordurl": "person/23456", "recordid": 23456, "recordtype": "person", "name": "Rob Smith" } ] } } } }

You can optionally pass an array of list options – see the section on Specifying a List of Records. In the following example, we specify a limit of one record.

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "read", "recordtype": "organisation", "recordid": 56789, "values": [ "Name", "People": { "limit": 1 } ] }

Sample Response

{ "success": true, "record": { "recordurl": "organisation/56789", "recordid": 56789, "recordtype": "organisation", "name": "Smith & Sons", "values": { "Name": "Smith & Sons", "People": { "recordtype": "person", "count": 1, "total": 2, "records": [ { "recordurl": "person/12345", "recordid": 12345, "recordtype": "person", "name": "John Smith" } ] } } } }

In the following example, we specify a sort order:

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "read", "recordtype": "organisation", "recordid": 56789, "values": [ "Name", "People": { "sortby": "FirstName", "sortorder": "DESC" } ] }

Sample Response

{ "success": true, "record": { "recordurl": "organisation/56789", "recordid": 56789, "recordtype": "organisation", "name": "Smith & Sons", "values": { "Name": "Smith & Sons", "People": { "recordtype": "person", "count": 2, "total": 2, "records": [ { "recordurl": "person/23456", "recordid": 23456, "recordtype": "person", "name": "Rob Smith" }, { "recordurl": "person/12345", "recordid": 12345, "recordtype": "person", "name": "John Smith" } ] } } } }

You can specify the precise values that you wish to be returned in a sub-list, nested as necessary. The following sample request asks for the FirstName, LastName, Email and Notes of each Person in the organisation, and for each Note, returns the Note text and Contact Date. The full response is not shown due to the amount of nesting involved, but experimentation will allow you to test the full potential of this feature.

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "read", "recordtype": "organisation", "recordid": 56789, "values": [ "Name", "People": { "sortby": "FirstName", "sortorder": "DESC", "values": { "FirstName", "LastName", "Email", "Notes": { "values": { "Note", "ContactDate" } } } } ] }

Full Record Details

If you request a record and don’t provide a specific set of values to be returned, then the response will include the entire details of the record, organised as the record would be presented in a User Interface, including grouping fields within their display sets, providing lists of Steps, Notes and Files. This is a quick and convenient way to access all the information about a single record without resorting to multiple individual queries.

The record response includes the following:

  • fields – array of display set names each containing an array of fields with name, title, current value and editable flag
  • steps – array of steps currently valid for the record. Use these as part of CRM-type next-best-action processes to offer guided behaviour on each record. Each step has a title, id, description and an icon name.
  • notes – array of notes in reverse date order (most recent first) – each note includes the date, subject, note text and created date/time
  • files – nested array of files/folders held on the record. Each folder contains filecount, being the total number of files (excluding directories) in the folder and all its sub-folders then an array of files, each of which is either another sub-folder structure, or an individual file containing name, dir flag, extension, size in bytes, icon name, date/time created, and the file’s record id (used to obtain the file’s contents using the getfile API call)

Sample Request

{ "account": *** your account id ***, "apikey": "*** your api key ***", "action": "read", "recordtype": "person", "recordid": 12345 }

Sample Response

{ "success": true, "record": { "recordurl": "person/12345", "recordid": 12345, "recordtype": "person", "name": "John Smith", "fields": { "Details": [ { "name": "FirstName", "title": "First Name", "value": "John", "editable": true }, { "name": "LastName", "title": "Last Name", "value": "Smith", "editable": true }, … ], "Contact": [ { "name": "Address", "title": "Address", "value": null, "editable": true }, … ], … }, "steps": [ { "title": "Enter Phone Number", "id": 99999, "description": …, "icon": "phone" } ], "notes": [ { "date": "2020-01-01", "subject": "Happy New Year", "note": …, "created": "2020-01-01 01:00:00" }, … ], "files": { "filecount": 7, "files": [ { "filecount": 1, "files": [ { "name": "JSmith.jpg", "dir": false, "ext": "jpg", "size": 34982, "icon": "fileimage", "date": …, "recordid": 123456 } ], "name": "Gallery", "dir": true }, … ] } } }