Working with List Endpoints¶
This guide explains how to effectively use list endpoints in TransactAPI. All list endpoints in this API follow a consistent pattern, allowing for efficient querying, filtering, and sorting of data.
Basic Structure¶
A typical request to a list endpoint looks like this:
Where {resource} is the name of the resource you're querying (e.g., ppex/orders, parties, accounts, links, trades etc.).
Query Parameters¶
List endpoints support the following query parameters:
limit: Number of records to returnoffset: Number of records to skip before starting to return resultsfilter: Conditions to filter the resultssort: Field(s) and direction to sort the results
Pagination¶
Use limit and offset for pagination:
This returns 10 records, starting from the 21st record.
Offset is for browsing, not for large syncs. The cost of an
offsetrequest grows with its depth — to return a page deep in the result set, the server must scan and discard every earlier row first, so response time climbs the further you page. It is not suitable for crawling large datasets or full-table exports. To page through large or growing datasets efficiently, use keyset pagination instead.
Sorting¶
Use the sort parameter to specify the field and direction for sorting:
Use :asc for ascending order and :desc for descending order.
Filtering¶
The filter parameter allows you to specify conditions for the returned data. You can use simple filters, array filters, and range filters.
-
Simple filter (exact match):
-
Array filter (IN clause):
-
Range filter:
For range filters, you can specify inclusivity:
GET /v3/{resource}?filter[fieldName][min]=minValue&filter[fieldName][max]=maxValue&filter[fieldName][min_inclusive]=false&filter[fieldName][max_inclusive]=false
By default, ranges are inclusive. Use min_inclusive=false or max_inclusive=false to make them exclusive. This works well for date ranges where you want to get all records that were created on a particular day.
GET /v3/ppex/orders?filter[updatedDate][min]=1999-01-22&filter[updatedDate][max]=1999-01-23&filter[updatedDate][max_inclusive]=false
This will retrieve only records that were updated on January 22, 1999. You can also get records from a particular hour of the day:
GET /v3/ppex/orders?filter[updatedDate][min]=1999-01-22T10:00:00-0500&filter[updatedDate][max]=1999-01-22T11:00:00-0500&filter[updatedDate][max_inclusive]=false
This will retrieve only records that occurred during the 10 'o'clock hour Eastern Standard Time.
- Multiple filters:
Multiple filters are combined with AND logic.
- Filters can also be defined using JSON syntax:
GET /v3/{resource}?filter={"fieldName": "value"}
GET /v3/{resource}?filter={"field1": "value1", "field2":{"min":minValue, "max": maxValue, "maxInclusive": false}
Advanced Filtering¶
TransactAPI supports advanced filtering options, allowing for more complex and precise data queries. You can use various operators to filter your results based on different conditions.
Filter Operators¶
The following operators are now available for filtering:
eq: Equal tone: Not equal togt: Greater thangte: Greater than or equal tolt: Less thanlte: Less than or equal toin: In a list of valuesnin: Not in a list of valueslike: Contains the value. The API adds the wildcards;%and_in the value match those characters literallybetween: Between two values (inclusive)
Using Advanced Filters¶
To use these advanced filters, you can specify them in the filter parameter using JSON syntax. Here are some examples:
-
Equal to:
-
Not equal to:
-
Greater than:
-
Less than or equal to:
-
In a list of values:
-
Contains:
-
Between two values:
Combining Multiple Filters¶
You can combine multiple filters in a single query. The filters will be applied with AND logic:
GET /v3/{resource}?filter={"field1": {"gt": 100}, "field2": {"in": ["A", "B"]}, "field3": {"like": "test"}}
This query will return results where field1 is greater than 100 AND field2 is either "A" or "B" AND field3 contains the word "test".
Range Filters¶
The existing range filter syntax is still supported and works as before:
GET /v3/{resource}?filter={"fieldName": {"min": minValue, "max": maxValue, "min_inclusive": true, "max_inclusive": false}}
Data Type Handling¶
The API automatically handles data type conversion for date/time and numeric values:
- Date and date-time values in ISO 8601 form (
YYYY-MM-DD, optionally followed by a time and offset, such as2023-06-01T10:00:00-0500) are converted to the format "YYYY-MM-DD HH:MM:SS". Other strings, including IDs, are compared as given - Numeric values are converted to floating-point numbers
Error Handling¶
If an invalid filter is provided, the API will return a 422 error with the description "invalid filter". Always ensure that your filter syntax is correct and that you're using valid field names and operators.
Efficient Pagination for Large Datasets (Keyset)¶
For large or continuously growing datasets — full syncs, incremental exports, or crawling an entire resource — use keyset pagination (also called cursor pagination) instead of offset. Rather than skipping a growing number of rows on every page, you carry forward a value from the last record you received and ask for the records that come after it. Each page costs the same regardless of how deep you are, so response time stays flat as the dataset grows.
Cursor pagination (ppex/orders, ppex/trades)¶
Coming soon to all list endpoints. Cursor pagination is available on
ppex/ordersandppex/tradesand will be extended to every list endpoint.
A cursor is a token that marks where a page of results ended. You send it back to get the next page. The cursor also remembers the query parameters of your first request, so you don't send them again.
To use cursor pagination, add paging=cursor to your first request. Results must be sorted by createdDate, which is the default sort. In cursor pagination, pagination holds only nextCursor:
- a string when there are more records to fetch;
nullwhen this is the last page.
Cursor pagination doesn't use offset, and doesn't return totalRecords, startIndex, or endIndex. limit sets the page size.
To page through results:
- Request the first page with
paging=cursorand any other query parameters you need:filter,sort,limit,deleted, andinclude. - Read
pagination.nextCursorfrom the response. - Request the next page with
cursor=<nextCursor>as the only query parameter. The API applies the first request'sfilter,sort,limit,deleted, andincludeto this page and to every page after it. - Repeat steps 2 and 3 until
nextCursorisnull.
# first page
GET /v3/ppex/orders?paging=cursor&filter[createdDate][min]=2026-11-06T21:00:00Z&sort=createdDate:asc&limit=500
# response
{
"statusCode": "101",
"statusDesc": "Ok",
"ppex_orders": [ ... ],
"pagination": {
"nextCursor": "AZQI67FKuChlfKGxXCJaV41lMd6C_-2xuz6v9EpoveCVRFjj..."
}
}
# next page
GET /v3/ppex/orders?cursor=AZQI67FKuChlfKGxXCJaV41lMd6C_-2xuz6v9EpoveCVRFjj...
Each record is returned exactly once, including records that share a createdDate.
Things to know:
- Treat the cursor as an opaque value. Don't parse or change it. It works only with the API key and endpoint that returned it.
- Send
cursoralone. Addingoffset,limit,filter,sort,deleted,include, orpagingreturns a 400. To change any of them, request a new first page. - Sort by
createdDate.paging=cursorwith another sort, such asexecutionTimeorupdatedDate, returns a 400. Page those sorts withoffset. - No
offsetwithpaging=cursor. Addingoffsetreturns a 400. UNAVAILABLEcursor. If a cursor can't be created, the first page returnsnextCursorasUNAVAILABLE. The records in that response are valid. Continue withoffset(withoutpaging), or request a new first page later.UNAVAILABLEonly appears on a first page, never on a page requested withcursor.- Errors. A changed cursor, or one used with a different API key or endpoint, returns a 422 with the description "invalid cursor". If cursors are temporarily unavailable, a request with
cursorreturns a 503.
Filter-based keyset pagination¶
On endpoints without cursor support, keyset pagination uses the filter and sort parameters you already know. On ppex/orders and ppex/trades, use cursor pagination instead.
- Sort ascending by a field that is set when the record is created and never changes, such as
createdDate. - Fetch the first page with no lower bound.
- Remember the highest value of the sort field in the page.
- Fetch the next page with that value as an inclusive lower bound, and drop any record whose id you have already received. The bound is inclusive because several records can share one value:
createdDatehas one-second resolution, and an exclusive bound would skip the rest of a group that a page boundary splits. - Stop when a page returns fewer than
limitrecords.
Range-filter form (min, inclusive by default):
# first page
GET /v3/{resource}?limit=500&sort=createdDate:asc
# each subsequent page
GET /v3/{resource}?limit=500&sort=createdDate:asc&filter[createdDate][min]=<last createdDate received>
Operator form (gte):
GET /v3/{resource}?limit=500&sort=createdDate:asc&filter={"createdDate":{"gte":"<last createdDate received>"}}
This approach misses records only if more than limit records share a single value of the sort field. Keep offset at 0 (or omit it) and advance the bound; that is what keeps each page fast.
Response Format¶
List endpoints typically return responses in this format:
{
"statusCode": "101",
"statusDesc": "Ok",
"data": [
{
// Resource-specific fields
},
// More items...
],
"pagination": {
"totalRecords": number,
"startIndex": number,
"endIndex": number
}
}
On ppex/orders and ppex/trades, pagination holds only nextCursor when the request sets paging=cursor or cursor; see Cursor pagination.
Tips and Best Practices¶
- Start with a small
limitto test your query before requesting larger datasets. - Use filters to reduce the amount of data transferred and processed.
- When using date or numeric ranges, the API automatically converts values to the appropriate format.
- Combine filters and sorting to get precisely the data you need.
- Pay attention to the
paginationobject in the response to handle large datasets effectively.
Error Handling¶
If your request is invalid or an error occurs, the API will return an appropriate error code and description. Always check the statusCode and statusDesc in the response. The API implements robust error handling to provide clear feedback on request issues. Here are common error scenarios:
- Invalid Pagination Parameters:
- If
offsetorlimitis not a valid integer, you'll receive a 422 error with code "1422" and a description explaining the issue. - If
limitis out of the allowed range (1 to 500), you'll get a 422 error with code "239" and a description of the valid range. -
If
offsetis negative or exceeds the total number of records, you'll receive a 422 error with code "239" and a description of the valid range. Note that for empty result sets, even an offset of 0 will trigger this error, as it technically exceeds the total number of records (which is 0). -
Cursor Errors:
- If
cursorwas changed, or is used with a different API key or endpoint, you'll receive a 422 error with the description "invalid cursor". - If
cursoris combined withoffset,limit,filter,sort,deleted,include, orpaging, you'll receive a 400 error naming the parameter. Ifpagingis any value other thancursororoffset, ifpaging=cursoris combined withoffset, or is used with a sort other thancreatedDate, you'll receive a 400 error. -
If cursors are temporarily unavailable, or
cursorisUNAVAILABLE, you'll receive a 503 error with code "1503". Start again from a first page, or page withoffset. -
Invalid Filter:
- If the
filterparameter cannot be decoded (for JSON-encoded filters), you'll get a 400 error. -
If the filter contains invalid fields or values, you'll receive a 422 error with a description "invalid filter".
-
Authorization Issues:
-
If the required scopes are not granted, you'll get a 403 error with the description "permission denied".
-
General Errors:
- Other errors will return appropriate HTTP status codes (e.g., 400 for bad requests, 500 for server errors) with a descriptive message.
Error responses follow this general structure:
This guide provides a general overview of working with list endpoints in TransactAPI. For specific details about individual endpoints, please refer to the dedicated documentation for each resource.