# List contacts

**GET /contacts**

The calling agent's contacts, filterable and sortable, each row carrying its Scout Score and trend, with alert counts and activity counts on request.

Requires the `contacts:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).


## Servers
- https://www.realscout.com/api/agent/v1: https://www.realscout.com/api/agent/v1 ()


## Authentication methods
- Bearer auth


## Parameters


### Query parameters

- **name** (string)
  Only contacts whose first or last name contains this substring (case-insensitive).

- **email** (string)
  Only the contact at exactly this address, ignoring case — the key create_contact matches on, so this is the one to ask "do I already have them?" with.

- **external_user_key** (string)
  The caller's own id for the contact, exact match; not enforced unique, so a page may hold more than one match.

- **tag** (string)
  Only contacts carrying this tag (case-insensitive exact match).

- **emailable** (boolean)
  Only contacts RealScout can (true) or cannot (false) email.

- **status** (string)
  Only contacts with this status.

- **created_after** (string(date-time))
  Only contacts created at or after this ISO-8601 timestamp.

- **created_before** (string(date-time))
  Only contacts created at or before this ISO-8601 timestamp.

- **updated_after** (string(date-time))
  Only contacts changed at or after this ISO-8601 timestamp — the filter a CRM sync pages on.

- **updated_before** (string(date-time))
  Only contacts changed at or before this ISO-8601 timestamp.

- **last_active_after** (string(date-time))
  Only contacts last active at or after this ISO-8601 timestamp.

- **last_active_before** (string(date-time))
  Only contacts last active at or before this ISO-8601 timestamp.

- **group** (string)
  Restrict to one of the Dashboard highlight groupings: most_engaged, recently_reengaged, or slipping_away. Composes with every filter above, and implies scout_score ordering.

- **sort** (string)
  created_at (default), last_active_at, or scout_score; contacts with no value sort last.

- **order** (string)
  DESC (default) or ASC.

- **include** (array[string])
  Comma-separated: alerts adds alerts, a summary per alert family with how many are still scheduled to send and when that family last sent; activity adds activity, the window's action counts. Both are the same shape get_contact returns for the same names. The Scout Score and its trend are on every row and need no include.

- **window_days** (integer)
  Look-back window in days for the activity counts and the group thresholds, 1 to 90.

- **cursor** (string)
  Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.

- **limit** (integer)
  Page size, 1 to 100.



## Responses
### 200
OK
#### Headers

- **X-RateLimit-Limit** (integer)
  Calls allowed in the current window.

- **X-RateLimit-Remaining** (integer)
  Calls left in the current window.

- **X-RateLimit-Reset** (integer)
  Epoch seconds at which the window resets.


#### Body: application/json (object)
- **data** (array[object])

- **has_more** (boolean)

- **next_cursor** (string | null)
  Send as cursor for the next page; null on the last one.


### 400
The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.

#### Body: application/json (object)
- **error** (object)


### 401
Invalid or missing bearer token.

#### Body: application/json (object)
- **error** (object)


### 403
The credential was not granted the scope this call requires.

#### Body: application/json (object)
- **error** (object)


### 404
Not found, or not yours: the two are indistinguishable on purpose.

#### Body: application/json (object)
- **error** (object)


### 429
Rate limit exceeded; `Retry-After` says when to try again.
#### Headers

- **Retry-After** (integer)
  Seconds until the budget refills.


#### Body: application/json (object)
- **error** (object)


### 500
Something went wrong on our side.

#### Body: application/json (object)
- **error** (object)



[Powered by Bump.sh](https://bump.sh)