---
title: "Sorting and time filters"
description: "Order list results with sort_by and order, and narrow them to a time range with since, until, and modified_since."
canonical_url: https://developer.onepagecrm.com/api/sorting/
source: Markdown mirror of https://developer.onepagecrm.com/api/sorting/
---

List endpoints return records in a default order. Two sets of query
parameters let you change that: **sorting** by a field, and **filtering**
by modification time.

## Sort by field

| Parameter | Type | Description |
| --- | --- | --- |
| `sort_by` | string | Field to sort by (e.g. `first_name`, `email`, `date`) |
| `order` | string | `asc` or `desc`. Default is `asc` |

Sort contacts by first name, Z to A:

```bash
curl -u "USER_ID:API_KEY" \
  "https://app.onepagecrm.com/api/v3/contacts.json?sort_by=first_name&order=desc"
```

## Filter by time

Return only records that fall in a given time range. All values are Unix
timestamps (seconds since the epoch).

| Parameter | Type | Description |
| --- | --- | --- |
| `since` | Unix timestamp | Records modified at or after this time |
| `until` | Unix timestamp | Records modified at or before this time |
| `modified_since` | Unix timestamp | Only records modified since this time |
| `unmodified_since` | Unix timestamp | Only records unmodified since this time |
| `date_filter` | Unix timestamp | Filter by a specific date field rather than modified time, when combined with `since` and `until` |

By default `since`/`until` apply to the *modified* time. Pass `date_filter`
to apply them to a specific date field on the record instead.

Fetch contacts modified in the last hour (shell computes the timestamp):

```bash
since=$(date -d '1 hour ago' +%s)
curl -u "USER_ID:API_KEY" \
  "https://app.onepagecrm.com/api/v3/contacts.json?modified_since=$since"
```

## Tips

- **Combine with [pagination](/api/pagination/).** Sort and filter narrow
  the set; `page`/`per_page` walk it.
- **Use `modified_since` for incremental syncs.** Store the timestamp of
  your last successful pull and pass it next time to fetch only what
  changed.
- **Timestamps are seconds, not milliseconds.** A 13-digit value will look
  like the year 50,000+ and return nothing.

## What to read next

- **[Pagination](/api/pagination/)** — walk a sorted, filtered list page by page.
- **[API reference](/api/reference/)** — which endpoints are lists, and their other filter parameters.
- **[OQL](/oql/overview/)** — richer queries and aggregates when parameters aren't enough.