Skip to content

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:

GET /v3/{resource}

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:

  1. limit: Number of records to return
  2. offset: Number of records to skip before starting to return results
  3. filter: Conditions to filter the results
  4. sort: Field(s) and direction to sort the results

Pagination

Use limit and offset for pagination:

GET /v3/{resource}?limit=10&offset=20

This returns 10 records, starting from the 21st record.

Offset is for browsing, not for large syncs. The cost of an offset request 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:

GET /v3/{resource}?sort=fieldName:asc

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.

  1. Simple filter (exact match):

    GET /v3/{resource}?filter[fieldName]=value
    

  2. Array filter (IN clause):

    GET /v3/{resource}?filter[fieldName][]=value1&filter[fieldName][]=value2
    

  3. Range filter:

GET /v3/{resource}?filter[fieldName][min]=minValue&filter[fieldName][max]=maxValue

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.

  1. Multiple filters:
GET /v3/{resource}?filter[field1]=value1&filter[field2][min]=minValue&filter[field2][max]=maxValue

Multiple filters are combined with AND logic.

  1. 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:

  1. eq: Equal to
  2. ne: Not equal to
  3. gt: Greater than
  4. gte: Greater than or equal to
  5. lt: Less than
  6. lte: Less than or equal to
  7. in: In a list of values
  8. nin: Not in a list of values
  9. like: Contains the value. The API adds the wildcards; % and _ in the value match those characters literally
  10. between: 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:

  1. Equal to:

    GET /v3/{resource}?filter={"fieldName": {"eq": "value"}}
    

  2. Not equal to:

    GET /v3/{resource}?filter={"fieldName": {"ne": "value"}}
    

  3. Greater than:

    GET /v3/{resource}?filter={"fieldName": {"gt": 100}}
    

  4. Less than or equal to:

    GET /v3/{resource}?filter={"fieldName": {"lte": "2023-06-01"}}
    

  5. In a list of values:

    GET /v3/{resource}?filter={"fieldName": {"in": ["value1", "value2", "value3"]}}
    

  6. Contains:

    GET /v3/{resource}?filter={"fieldName": {"like": "pattern"}}
    

  7. Between two values:

    GET /v3/{resource}?filter={"fieldName": {"between": ["2023-01-01", "2023-12-31"]}}
    

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 as 2023-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/orders and ppex/trades and 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;
  • null when 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:

  1. Request the first page with paging=cursor and any other query parameters you need: filter, sort, limit, deleted, and include.
  2. Read pagination.nextCursor from the response.
  3. Request the next page with cursor=<nextCursor> as the only query parameter. The API applies the first request's filter, sort, limit, deleted, and include to this page and to every page after it.
  4. Repeat steps 2 and 3 until nextCursor is null.
# 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 cursor alone. Adding offset, limit, filter, sort, deleted, include, or paging returns a 400. To change any of them, request a new first page.
  • Sort by createdDate. paging=cursor with another sort, such as executionTime or updatedDate, returns a 400. Page those sorts with offset.
  • No offset with paging=cursor. Adding offset returns a 400.
  • UNAVAILABLE cursor. If a cursor can't be created, the first page returns nextCursor as UNAVAILABLE. The records in that response are valid. Continue with offset (without paging), or request a new first page later. UNAVAILABLE only appears on a first page, never on a page requested with cursor.
  • 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 cursor returns 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.

  1. Sort ascending by a field that is set when the record is created and never changes, such as createdDate.
  2. Fetch the first page with no lower bound.
  3. Remember the highest value of the sort field in the page.
  4. 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: createdDate has one-second resolution, and an exclusive bound would skip the rest of a group that a page boundary splits.
  5. Stop when a page returns fewer than limit records.

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

  1. Start with a small limit to test your query before requesting larger datasets.
  2. Use filters to reduce the amount of data transferred and processed.
  3. When using date or numeric ranges, the API automatically converts values to the appropriate format.
  4. Combine filters and sorting to get precisely the data you need.
  5. Pay attention to the pagination object 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:

  1. Invalid Pagination Parameters:
  2. If offset or limit is not a valid integer, you'll receive a 422 error with code "1422" and a description explaining the issue.
  3. If limit is out of the allowed range (1 to 500), you'll get a 422 error with code "239" and a description of the valid range.
  4. If offset is 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).

  5. Cursor Errors:

  6. If cursor was changed, or is used with a different API key or endpoint, you'll receive a 422 error with the description "invalid cursor".
  7. If cursor is combined with offset, limit, filter, sort, deleted, include, or paging, you'll receive a 400 error naming the parameter. If paging is any value other than cursor or offset, if paging=cursor is combined with offset, or is used with a sort other than createdDate, you'll receive a 400 error.
  8. If cursors are temporarily unavailable, or cursor is UNAVAILABLE, you'll receive a 503 error with code "1503". Start again from a first page, or page with offset.

  9. Invalid Filter:

  10. If the filter parameter cannot be decoded (for JSON-encoded filters), you'll get a 400 error.
  11. If the filter contains invalid fields or values, you'll receive a 422 error with a description "invalid filter".

  12. Authorization Issues:

  13. If the required scopes are not granted, you'll get a 403 error with the description "permission denied".

  14. General Errors:

  15. 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:

{
  "statusCode": "ERROR_CODE",
  "statusDesc": "Error description",
  "data": []
}

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.