Skip to main content

Response Details

List Response Format#

API endpoints that return a list of results follow the format below.

Attributes

meta.pathstring
Path of the API request
meta.countstring
Total number of objects in list. See pagination.
meta.lastUpdatedtimestamp
Unix Timestamp of when data was retrieved from AppFolio®. See Response Polling.
meta.statusstring: 'ok' | 'stale' | 'updating'
Status of the returned data. See Response Polling.
meta.statusDetails.codenumber
Status Detail Code of the last attempt to get data. See Response Polling.
meta.statusDetails.messagestring
Status message of the last attempt to get data. See Response Polling.
linksobject
Links used for pagination, see Pagination.
dataarray
The document's primary data
 
List Response Format
{
"meta": {
"path": "/v1/properties",
"count": 172,
"lastUpdated": 1610992228,
"status": "ok"
},
"links": {
"next": "/v1/properties?page[after]=nnnnnn"
},
"data": [
{ ...object },
...
]
}

Pagination#

The total number of records matching your query is available as meta.count. In order to page through requests, it's important to use the links.prev and links.next in the response body. These links are implemented based on the JSON API specification. They will allow you to page through results without missing or duplicating an entry.

While using pagination will correctly page through results, the results may be updated via a successful request or a scheduled job. Ensure meta.status equals "ok" while paging through results. If it changes to "stale", we recommend polling the original URL at the url property.

Note that the cursor used in page[before] and page[after] ensures the same data cache entry is used when paging through a list to avoid duplicates or mismatched information.

Errors#

The API responds with conventional HTTP response code in the event of an error.

Error Response Attributes#

Error responses also follow a specific format to help provide details.
statusCodenumber
Response HTTP status code.
typestring
The cause of the error. See list of API Error Types.
messagestring
English readable error message.
errorsarray
An array of field-based validation errors, when available.
 
Error Response Format
{
"statusCode": 422,
"type": "VALIDATION",
"message": "Missing required parameter.",
"errors": [
{
"field": "timePeriod",
"errors": [
"is required."
]
}
]
}

API Error Types#

Types of errors which may be returned by the API:
AUTHENTICATION
Issue validating API key. Make sure the API key has the right permissions and scope. See more here.
VALIDATION
One or more parameters was invalid. Check "errors": [...] for more details.
 

HTTP Status Codes#

HTTP status codes the API may respond with:
200OK
Success.
400BAD REQUEST
The request is unacceptable, typically due to a missing or invalid parameter.
401UNAUTHORIZED
No valid API key.
402REQUEST FAILED
Valid request, but failed.
403FORBIDDEN
The API key does not have permission.
404NOT FOUND
The requested URL does not exist.
409CONFLICT
The request conflicts with another request.
422UNPROCESSABLE ENTITY
The request is not processible, likely due to validation errors.
429TOO MANY REQUESTS
The API key exceeded its rate limit.
500, 502, 503, 504SERVER ERROR
Something went wrong on Skywalk API's side. If you ever see one of these, please contact support.
 

Status Detail Codes#

Codes that may appear in response meta.statusDetails.code:
1GENERAL_RUNTIME_ERROR
General error getting data.
5INVALID_APPFOLIO_HOST
Invalid Appfolio domain.
6VERIFY_REQUIRED
User verification required.
7VERIFY_ERROR
User verification error.
8LOGIN_FAILED
Failed to log in with user credentials.
9INVALID_REPORT
Invalid Appfolio report.
10REPORT_NO_PERMISSIONS
Appfolio user does not have permissions to access the data.
21TIMEOUT
Timeout.
Â