REST API - Getting Started

Introduction

Accela REST API provides resources to build Citizen and Agency apps using Civic Apps platform.

Headers

Below HTTP headers are required in some of API requests.

HTTP Header		Description
Key	Value	Description
Content-Type	{content-type}	Specify content type in HTTP body for current request. Replace "{content-type}" with actual content type value, usually the value is application/ json .
Accept	{accept}	Specify content type in HTTP body for current response. Replace "{accept}" with actual Accept value, usually the value is application/json.
Authorization	{access token}	Specify authentication access token for current request. Replace "{access token}" with actual access token value.
x-accela-appid	{app id}	Specify app id for current request. Replace "{app id}" with actual app id value. To get app id, you can create a new app in My App , and then copy the generated app id.
x-accela-appsecret	{app secret}	Specify app secret for current request. Replace "{app secret}" with actual app secret value. To get app secret, you can create a new app in My App , and then copy the generated app secret.
x-accela-environment	{environment name}	Specify environment for current request, please contact agency administrator to get environment supported by thatagency. Replace {environment name} with actual environment value.
x-accela-agency	{agency name}	Specify agency name for current request. Replace {agency name} with actual agency name value. For some citizen apps, you can get agency name dynamically by invoking API "get agency name by coordinates". For more information about agency name, contact agency administrator.

Required request HTTP Headers vary based on authorization type as below.

Request Authorization Type	Required Request HTTP Headers
No authorization required	Content-Type
	Accept
	x- accela - appid
	x-accela-environment

Access token	Content-Type
	Accept
	x- accela - appid
	Authorization
	x- accela -agency (optional for some APIs, e.g. Geo Apis)

App Credentials	Content-Type
	Accept
	x- accela - appid
	x- accela - appsecret

Below headers are sent in the response.

HTTP Header		Description
Key	Value	Description
x-accela-traceId	{trace id}	Indicates trace id for http response, the id is used for diagnostics purposes. each response will contain a unique trace id.
x-accela-resp-message	{response message}	Indicate the response error message when there are any errors occurred. You can see the response message in response body as well.

Pagination

Accela REST API currently supports offset-based pagination.

Parameters used in http request for pagination are below :

Paging Key

Description

Offset

Indicates the offset start of each page by the number specified.

Start offset: 0

Default offset: 0

Limit

Indicates the number of items that are returned in each page.

Note this is an upper limit, if there are not enough items to return, then less than this number will be returned.

Default limit: 20

Max limit: 1000

Request Sample:

GET https://apis.accela.com/v3/records/?offset=0&limit=20&lang=en_US

Response paging info as below:

Paging Key	Description
totalRows	Indicates the total number of items in all pages combined.
hasMore	Indicates if there are more items available beyond current paged response.

Response Sample as below:

"page": {
    "totalRows": 79,
    "hasMore": true
}

Parameters Format

Accela REST API uses below format for parameter values.

Parameter Type	Format	Description
Date/date time	yyyy -MM- dd HH:mm:ss
Date range	yyyyMMdd-yyyyMMdd
Multiple values	e.g. Id1,id2,id3	Comma separated values

Errors

The following shows a common json error response resulting from a failed API call:

{
    "status": 403,
    "message": "You are not authorized to access the resource.",
    "code": "forbidden",
    "more": null,
    "traceId": "130527090003731-9b30f89c"
}

Following are HTTP statuses, error codes and descriptions.

HTTP Status	Error Code	Description
400	bad_request	Bad request
400	data_validation_error	Data validation error
400	invalid_uri	Invalid URL
401	unauthorized	Unauthorized
401	no_token	Token is required for the current request
401	token_expired	Current token is expired
401	invalid_token	Current token is invalid
401	unauthorized_app	Unauthorized app
401	no_app_credential	App credentials is required
403	forbidden	Current request is forbidden
404	resource_not_found	Current request resource is not found
500	internal_server_error	Internal server error occurred

There are special characters in Accela business entity IDs which conflict with reserved URL characters. These need to be escaped to work with REST APIs as resource IDs and pass in URLs. For example, Accela Record Type ID "ServiceRequest-Streets and Sidewalks-Snow Removal-NA" is encoded as "ServiceRequest-Streets.cand.cSidewalks-Snow.cRemoval-NA". Usually Accela API will encode these in responses before returning them as resource IDs.