Developer PortalUsing the API
API ScopesAPI CredentialsAPI LimitsAuthentication and AuthorizationAPI RequestsAPI ResponsesCustom Data FieldsUploading and Downloading DocumentsAPI EndpointsReporting EndpointsREST Hooks
REST Hooks and Event NotificationsAPI Responses
Anatomy of a GET Response
The response from a GET request to any of the API endpoints returns data in a structured JSON format. A typical GET response is shown below:
GET /api/rest/actions/3?include=actionTypes
{
"links": {
"actions.assignedTo": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/participants/{actions.assignedTo}",
"type": "participants"
},
"actions.division": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/divisions/{actions.division}",
"type": "divisions"
},
"actions.actionType": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/actiontypes/{actions.actionType}",
"type": "actiontypes"
},
"actions.primaryParticipants": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/participants/{actions.primaryParticipants}",
"type": "participants"
},
"actions.step": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/steps/{actions.step}",
"type": "steps"
},
"actions.billSettings": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/actionbillsettings/{actions.billSettings}",
"type": "actionbillsettings"
},
"actions.relatedActions": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/actions/{actions.relatedActions}",
"type": "actions"
},
"actiontypes.primaryParticipantType": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/participanttypes/{actiontypes.primaryParticipantType}",
"type": "participanttypes"
}
},
"actions": {
"id": 3,
"name": "Matter No 3",
"reference": null,
"priority": 0,
"status": "Active",
"statusTimestamp": "2020-04-03T12:33:58+13:00",
"isBillableOverride": null,
"createdTimestamp": "2020-04-03",
"modifiedTimestamp": "2020-04-30T11:27:31+12:00",
"isDeleted": "F",
"deletedBy": null,
"deletedTimestamp": null,
"isFavorite": "F",
"overrideBillingStatus": null,
"lastAccessTimestamp": "2020-04-03T12:34:30+13:00",
"links": {
"assignedTo": "10",
"division": "1",
"actionType": "7",
"primaryParticipants": [
"10"
],
"step": "7--0",
"billSettings": "3",
"relatedActions": null
}
},
"linked": {
"actiontypes": [
{
"id": 7,
"name": "General",
"description": "General Matter",
"copyrightHolder": "Legal Eagles Limited",
"copyrightContact": "http://www.legaleagles.com",
"copyrightEmail": "accounts@legaleagles.com",
"trackActualTime": "F",
"trackBillableTime": "F",
"isForMarketingCampaigns": "F",
"isForMarketingEvents": "F",
"isForEmployees": "F",
"isForCrm": "F",
"isForDebtCollection": "F",
"isDisabled": "F",
"isBillable": "T",
"enableActionImage": "T",
"defaultEmailSubject": null,
"logoFilename": "document-open-5.png",
"customLogoFilename": "",
"customLogoDirectory": "",
"customLogoFilesize": "",
"customLogoModifiedTimestamp": "",
"templateIdentifier": null,
"allowCloseWithOpenInvoice": "F",
"allowInlineCustomizing": "F",
"canCreate": "F",
"links": {
"primaryParticipantType": "27"
}
}
]
},
"meta": {
"paging": {
"actions": {
"recordCount": 1,
"pageCount": 1,
"page": 1,
"pageSize": 50,
"prevPage": null,
"nextPage": null
}
},
"debug": {
"requestTime": "0.078199",
"mem": "2.67mb",
"server": "app-003ff685daa3.ap-southeast-2.actionstepstaging.com",
"cb": "T21726-23073-7",
"time": "2020-05-01 14:54:08 +1200 (Pacific/Auckland)",
"appload": "0.16, 0.17, 0.11",
"app": "0.024655",
"db": "0.053544",
"dbc": "0.006721",
"qc": "64",
"uqc": "34",
"fc": "1,611",
"rl": null
}
}
}
A GET response is typically made up of the following sections:
Links Section
Contains a collection of links to secondary (related) resources and provides a uri template to retrieve that resource. In the above example you will notice under the actions (data) section are a number of links for the action resource:
"actions": {
"id": 3,
"name": "Matter No 3",
...
"links": {
"assignedTo": "10",
...
}
}
The link is read as "actions.assignedTo", which maps to one of the links shown at the top of the response:
"links": {
"actions.assignedTo": {
"href": "https://ap-southeast-2.actionstepstaging.com.actionstep.com/api/rest/participants/{actions.assignedTo}",
"type": "participants"
}
...
}
Depending on the nature of your application/integration you can use these links to retrieve information on secondary (related) resources
by substituting {actions.assignedTo} for the value in the data section.
Data Section
This section contains the primary resource(s) requested together with (where applicable) any includes.
NB: One important factor to be aware of in the structure of the data section is the difference between retieving a single resource compared to retrieving multiple resources.
A single resource is returned in the format of:
"actions": {
"id": 3,
"name": "Matter No 3",
...
}
Whereas multiple resources are returned in a JSON array format:
"actions": [
{
"id": 3,
"name": "Matter No 3",
...
},
{
"id": 14,
"name": "General Business Matter",
...
},
...
],
Linked Section
The linked section is a collection of resources, grouped by type, that are linked (related) to the primary resource. A linked resource will appear in the response if its a default related resource, or it has been specifically requested using the Include clause.
"linked": {
"actiontypes": [
{
"id": 7,
"name": "General",
"description": "General Matter",
"copyrightHolder": "Legal Eagles Limited",
"copyrightContact": "http://www.legaleagles.com",
"copyrightEmail": "accounts@legaleagles.com",
"trackActualTime": "F",
"trackBillableTime": "F",
"isForMarketingCampaigns": "F",
"isForMarketingEvents": "F",
"isForEmployees": "F",
"isForCrm": "F",
"isForDebtCollection": "F",
"isDisabled": "F",
"isBillable": "T",
"enableActionImage": "T",
"defaultEmailSubject": null,
"logoFilename": "document-open-5.png",
"customLogoFilename": "",
"customLogoDirectory": "",
"customLogoFilesize": "",
"customLogoModifiedTimestamp": "",
"templateIdentifier": null,
"allowCloseWithOpenInvoice": "F",
"allowInlineCustomizing": "F",
"canCreate": "F",
"links": {
"primaryParticipantType": "27"
}
}
]
},
Meta Data Section
Contains sets of additional data values useful to your application/integration development. Paging meta data can be used to build navigational functionality for traversing larger resource collections.
"meta" : {
"paging": {
"actions": {
"recordCount": 1,
"pageCount": 1,
"page": 1,
"pageSize": 50,
"prevPage": null,
"nextPage": null
}
},
...
}
NB: Paging meta data is included whether you are requesting a single resource or multiple resources.
The debug meta data contains a collection of statistical values that return telemetry for the request lifecycle. They can be used to analyse request performance, determine potential bottlenecks, and identify inefficient queries.
"meta" : {
"debug": {
"requestTime": "0.082762",
"mem": "3.34mb",
"server": "app-003ff685daa3.ap-southeast-2.actionstepstaging.com",
"cb": "T21726-23073-5",
"time": "2020-04-30 16:47:21 +1200 (Pacific/Auckland)",
"appload": "0.20, 0.27, 0.35",
"app": "0.029924",
"db": "0.052838",
"dbc": "0.006835",
"qc": "64",
"uqc": "34",
"fc": "1,611",
"rl": null
}
}
| Measure | Description |
|---|---|
| requestTime | The total time to process the request. |
| mem | The peak memory utilisation (in MBs) for processing the request. |
| server | The server host name that handled and processed the request. |
| cb | The source code branch tag (for internal use only). |
| time | The server time of day the request was made. |
| appload | Server load averages over three different time periods. |
| app | The total request processing time minus the total database processing time. |
| db | The total time the database engine consumed executing SQL statements. |
| dbc | The total time consumed in connecting to the database. |
| qc | The number of database queries executed. |
| uqc | The unique database query count. |
| fc | The total number of data rows fetched from the database. |
| rl | Rate limit (not currently implemented). |
All times are specified in seconds.
POST Response
Successfully creating one or more new resources will result in an http status code of 200 being returned. Although technically this should return an http status code of 201, a POST request always returns a GET response for the newly created resource(s).
PUT Response
Similarly to the POST response, successfully updating one or more existing resources will return an http status code of 200. A PUT request always returns a GET response for the modified resource(s).
DELETE Response
Successfully deleting one or more resources will return an http status code of 204 (No Content).
ERROR Response
If an error is detectded during the processing of a request an error response message is generated and returned. The JSON structure will contain a single "errors" object which can include a number of attributes (see example below).
NB: The content of an error response will vary depending on the nature of the error detected.
{
"errors":
{
"id" : "9bdfe0fb349f82144c0d177fc96e73baba9b2bbd",
"links":
{
"about":null
},
"status":404,
"code":"AS-TBC",
"title":"API Resource Not Found",
"detail":"The specified Resource 'Filenote' does not exist",
"source":
{
"pointer":null,
"parameter":null
},
"meta":[],
"rls":null
}
}
Error Attributes
| Attribute | Description |
|---|---|
| id | A unique (internal) identifier for this particular occurrence of the problem. |
| href | A URI that may yield further details about this particular occurrence of the problem. |
| status | The HTTP status code applicable to this problem, expressed as a string value. |
| code | An internal application-specific error code, expressed as a string value. See Error Codes for further information. |
| title | A short human-readable summary of the problem. This doesn't change from occurrence to occurrence of the problem, except for the purposes of localization. |
| detail | A human-readable explanation specific to this occurrence of the problem. |
| links | Associated resources which can be dereferenced from the request document. |
| path | The relative path to the relevant attribute within the associated resource(s). Will only exist for problems that apply to a single resource or type of resource. |
NB: The above list is not exhaustive. Other error attributes may be included in the response as required.