Skip to content

Working with List Endpoints

This guide explains how to effectively use list endpoints in Transact API. 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

Transact API 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: Pattern matching (using SQL LIKE syntax)
  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. Pattern matching: 

    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/time values are converted to the format "YYYY-MM-DD HH:MM:SS"
  • 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.

Keyset pagination uses the filter and sort parameters you already know — there is no separate cursor parameter:

  1. Sort ascending by an indexed, monotonically increasing field. On ppex/orders and ppex/trades, use executionTime — it is set once when the record is written, is never updated, has sub-second resolution, and is indexed, so pages stay ordered without a sort step.
  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 using that value as an exclusive lower bound (strictly greater than), so the last record of the previous page is not repeated.
  5. Stop when a page returns fewer than limit records.

executionTime is a high-resolution timestamp value; carry back the exact value you received in the previous page. The exclusive lower bound can be expressed two equivalent ways:

Range-filter form (min with min_inclusive=false):

# first page
GET /v3/ppex/trades?limit=500&sort=executionTime:asc

# each subsequent page
GET /v3/ppex/trades?limit=500&sort=executionTime:asc&filter[executionTime][min]=<last executionTime received>&filter[executionTime][min_inclusive]=false

Operator form (gt):

GET /v3/ppex/trades?limit=500&sort=executionTime:asc&filter={"executionTime":{"gt":"<last executionTime received>"}}

Because the bound is exclusive (strictly greater than the cursor), there is no boundary overlap to de-duplicate.

Tie handling. executionTime is sub-second, so it is very unlikely for two records to share the exact same value — but if that is a concern for your data, use an inclusive lower bound (min_inclusive=true / gte) and de-duplicate on a unique record id (for example tradeId or orderId) as you page.

Do not combine keyset pagination with offset — keeping offset at 0 (or omitting it) and advancing the cursor 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
  }
}

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. Invalid Filter:

  6. If the filter parameter cannot be decoded (for JSON-encoded filters), you'll get a 400 error.

  7. If the filter contains invalid fields or values, you'll receive a 422 error with a description "invalid filter".

  8. Authorization Issues:

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

  10. General Errors:

  11. 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 Transact API. For specific details about individual endpoints, please refer to the dedicated documentation for each resource.