---
title: "Query accounts"
method: POST
path: "/v2/accounts/query"
tags: ["Accounts"]
---

# Query accounts

`POST /v2/accounts/query`

## Request

- Base URL: `https://api.getpaid.io`
- URL: `https://api.getpaid.io/v2/accounts/query`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.getpaid.io/oauth/token` scopes: `accounts:read`
- TypeScript: <https://skmtc.dev/getpaid/apis/getpaid-api/docs/v2/accounts/query/post.ts> (a function with typed inputs; its response is checked against the schema)

Query accounts filtering, sorting and paginating results.

See [Queries](/operate/queries) for more examples and details about pagination and common query patterns.

## Headers

- `Getpaid-Idempotency-Key` string, required

## Request body

- QueryAccountsRequest
  - `type` 'accounts', required: The type of the Getpaid solution resources to query. Some query endpoints infer the resource type from the request path. In those cases, if this field is set, it must match the resource targeted by the request URL.
  - `first` integer: Pagination. The number of elements that will be retrieved.
  - `after` string: Pagination. The `cursor` from next page will be retrieved.
  - `filters` object: Filtering accounts.
    - `id` string, id: The unique identifier of the account.
    - `legal_name` string: The legal name of the account.
    - `country` string, country: The two-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
  - `sorts` object[]: Fields to sort the data by. If not set, the data will be sorted by the creation date descending.
    - `field` 'id' | 'created_at' | 'legal_name' | 'country', required: The field to sort by. Each field available can only be used once in the list.
    - `direction` 'ascending' | 'descending', required: The sort direction

## Response `200`

OK

- QueryAccountsResponse
  - `type` 'accounts', required
  - `cursor` string: The cursor to the last item. If non-empty, can be used to fetch the next page. If not set, there is no more elements.
  - `data` object[], required: The list of queried elements.
    - `id` string, id, required: The unique identifier of the account.
    - `legal_name` string, required: The legal name of the account.
    - `country` string, country, required: The two-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
    - `created_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `422`: Invalid Parameters
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/getpaid/apis/getpaid-api.md) - [All operations](https://skmtc.dev/getpaid/apis/getpaid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpaid/apis/getpaid-api/revisions/458eae3d49ad?raw)