back

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

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.

For more information, please refer to  Login - Getting Started .

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

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

Escape Characters

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 APIs will encode these in responses before returning them as resource IDs.
Characters Escaped Characters
. .0
- .1
% .2
/ .3
\\ .4
: .5
* .6
\ .7
< .8
> .9
| .a
? .b
space .c
& .d
# .e