Filtering & Sorting (SDA)

Filtering

Endpoints that return lists of resources (e.g., GET List all Transactions linked to an Account) support filtering, which forces the API to return only those results that match your desired data set.

note

You can only filter a resource by properties that it actually contains. For example, you can use starts_at to filter endpoints related to Transactions but not endpoints related to Trades.

The filtering scheme supports the following operators:

  • Exact match on one property: filter[state]=COMPLETED

    • This would return all resources with a state of COMPLETED.

  • Collection range of multiple properties: filter[state][]=COMPLETED&filter[state][]=FAILED

    • This would return all resources with a state of COMPLETED or FAILED.

  • gt (greater than): filter[property_name][gt]=2022-01-01T00:00:00Z

    • This would return all resources with a property_name (timestamp) value after midnight on January 01, 2022.

  • gte (greater than or equal to): filter[property_name][gte]=2022-01-01T00:00:00Z

    • This would return all resources with a property_name (timestamp) value from midnight on January 01, 2022, or later.

  • lte (less than or equal to): filter[property_name][lte]=2022-01-02T00:00:00Z

    • This would return all resources with a property_name (timestamp) value no later than midnight on January 01, 2022.

  • lt (less than): filter[property_name][lt]=2022-01-02T00:00:00Z

    • This would return all resources with a property_name (timestamp) value prior to midnight on January 01, 2022.

To filter a request, append the filter parameter to the request query as shown in the examples below. You can apply multiple filters in a single request, separated by &.

Examples

Match single values

GET .../transactions?filter[type]=DEPOSIT
Copy
Copied
// 200 OK

{
  "items": [
    {
      "id": "bf20c716075ea82a4b1f3f0b49657161atrx",
      "account_id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
      "type": "DEPOSIT",
      "state": "COMPLETED",
      "amount": "1.12340000",
      "fee_amount": "0.00000000",
      "created_at": "2019-04-02T13:15:47Z",
      "updated_at": "2019-04-02T13:15:47Z"
    }
  ]
}

Match any value in a set

GET .../transactions?filter[state][]=COMPLETED&filter[state][]=FAILED
Copy
Copied
// 200 OK

{
  "items": [
    {
      "id": "bf20c716075ea82a4b1f3f0b49657161atrx",
      "account_id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
      "type": "DEPOSIT",
      "state": "COMPLETED",
      "amount": "1.12340000",
      "fee_amount": "0.00000000",
      "created_at": "2019-04-02T13:15:47Z",
      "updated_at": "2019-04-02T13:15:47Z"
    }
  ]
}

A time range

GET .../transactions?filter[created_at][gte]=2022-01-01T00:00:00Z&filter[created_at][lt]=2022-01-02T00:00:00Z
Copy
Copied
// 200 OK

{
  "items": [
    {
      "id": "944eed5b06bc80a9cae92154fb78425catrx",
      "account_id": "721263078f2dcea6d7fa604aba51e90eacct",
      "type": "DEPOSIT",
      "state": "COMPLETED",
      "amount": "0.01000000",
      "fee_amount": "0.00000000",
      "created_at": "2022-01-01T13:20:54Z",
      "updated_at": "2022-01-01T13:21:00Z"
    }
  ]
}

Combine multiple filters

GET .../transactions?filter[state][]=COMPLETED&filter[state][]=FAILED&filter[type]=DEPOSIT
Copy
Copied
// 200 OK

{
  "items": [
    {
      "id": "bf20c716075ea82a4b1f3f0b49657161atrx",
      "account_id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
      "type": "DEPOSIT",
      "state": "COMPLETED",
      "amount": "1.12340000",
      "fee_amount": "0.00000000",
      "created_at": "2019-04-02T13:15:47Z",
      "updated_at": "2019-04-02T13:15:47Z"
    }
  ]
}

Sorting

Endpoints that return lists of resources (e.g., GET List all Transactions linked to an Account) support sorting, which reorders the results in the way that you specify.

To sort the results of an API call, append the sort[] parameter to the request query as shown in the examples below. Use the following format:

?sort[]=$ATTRIBUTE $DIRECTION

$ATTRIBUTE refers to the property of the resource by which to sort the results (e.g., created_at).

$DIRECTION refers to the direction in which to sort the results. Options are: asc for ascending, desc for descending.

By default, the API orders results by created_at desc and id asc.

Examples

Sort by one property in descending order

GET .../transactions?sort[]=created_at%20desc
Copy
Copied
// 200 OK

{
  "items": [
    {
      "id": "bf20c716075ea82a4b1f3f0b49657161atrx",
      "account_id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
      "type": "DEPOSIT",
      "state": "COMPLETED",
      "amount": "1.12340000",
      "fee_amount": "0.00000000",
      "created_at": "2020-10-09T13:15:47Z",
      "updated_at": "2020-10-09T13:15:47Z"
    },
    {
      "id": "bf20c716075ea82a4b1f3v0b49a57182atrx",
      "account_id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
      "type": "DEPOSIT",
      "state": "COMPLETED",
      "amount": "1.00010000",
      "fee_amount": "0.00000000",
      "created_at": "2020-10-01T11:17:47Z",
      "updated_at": "2020-10-01T11:17:47Z"
    }
  ]
}

Sort by multiple properties in descending order

GET .../transactions?sort[]=created_at%20desc&sort[]=state%20desc
Copy
Copied
// 200 OK

{
  "items": [
    {
      "id": "bf20c716075ea82a4b1f3f0b49657161atrx",
      "account_id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
      "type": "DEPOSIT",
      "state": "COMPLETED",
      "amount": "1.12340000",
      "fee_amount": "0.00000000",
      "created_at": "2020-10-09T13:15:47Z",
      "updated_at": "2020-10-09T13:15:47Z"
    },
    {
      "id": "bf20c716075ea82a4b1f3v0b49a57182atrx",
      "account_id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
      "type": "DEPOSIT",
      "state": "COMPLETED",
      "amount": "1.00010000",
      "fee_amount": "0.00000000",
      "created_at": "2020-10-01T11:17:47Z",
      "updated_at": "2020-10-01T11:17:47Z"
    }
  ]
}