Responses in the Firstup Partner API use RESTful response bodies in order to be descriptive and predictable. Each endpoint includes its own documentation illustrating the responses and errors expected, but this section describes the typical responses you can expect to encounter.
Every response provides the following special response headers:
- X-Program-Id: the program id of the scope of the request.
- X-User-Id: the user id of the acting (authenticated) user.
Endpoints that return data will always wrap that data in a "data" property, whether the response data is an object or array.
Successful responses that return data always wrap their data in a "data" property and include a “meta” object at the root level when meta information is available (see below).
While different endpoints use different response codes that correspond to the purpose and design of the endpoint, the following are general patterns you can expect:
- Reading of data in either list or individual form uses 200 OK.
- Creating new records uses 201 Created if a record was created immediately, and 202 Accepted if a record will be created but cannot be completed immediately.
- Updating existing records uses 200 OK if the record was updated immediately, and 202 Accepted if the update will be performed but cannot be completed immediately.
- Executing actions on existing records (such as “archive” or “publish”) uses 200 OK if the record was updated immediately, and 202 Accepted if the update will be performed but cannot be completed immediately. In some cases, if the action does not need to respond with any data, 204 No Content indicates immediate success without a response body.
- Deletion of records or data uses 200 OK if the data was deleted immediately, and 202 Accepted if the update will be performed but cannot be completed immediately.
Each endpoint will describe the response statuses it returns.
Every successful response provides metadata relating to the response in the root of the response body. The meta property includes information that helps to explain the aspects that went into determining what data to return in the response, including pagination, filtering, and sorting.
For endpoints that allow pagination, the metadata includes a pagination property. The page property includes values used in pagination even if the request did not specify a page.
For endpoints that use page pagination, the following properties are provided:
- page_size: The coerced or defaulted page size value from the request.
- page: The coerced or defaulted page number value from the request.
- total_records: A count of the total items in the collection according to the filters.
For endpoints that use cursor pagination, the following properties are provided:
- page_size: The coerced or defaulted page size value from the request.
- cursor: The cursor used for the current set of records.
- next: The cursor to use for the next set of records.
For endpoints that allow filtering, the metadata includes a filters property. The filters property includes default values used in filtering even if the request did not specify filters. For example, if a filter such as “status” is set to “registered” by default, the filter’s property will include status: “registered”.
For endpoints that allow searches, the metadata includes a search property that indicates the value of the search parameter used in the request. If the search property was reformatted or transformed in any way, it will be represented in the meta object in its transformed format.
For endpoints that allow sorting, the metadata includes a sort property that indicates the list of sort keys used in order.
Including page size, total records, cursor, filtering, etc.
Pagination Overview
Includes page number, size, cursor, start index and count.
Filtering Overview
Includes enum based, equals based, timestamp, any property, multiple properties, multiple values and errors.
Refer to our main documentation on error responses.