---
title: "Get users"
method: GET
path: "/v1/users"
tags: ["Users"]
---

# Get users

`GET /v1/users`

## Request

- Base URL: `https://app.aptrinsic.com`
- URL: `https://app.aptrinsic.com/v1/users`
- Auth: none declared
- TypeScript: <https://skmtc.dev/gainsight/apis/gainsight-px-rest-api/docs/v1/users/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieves users.  Supports filtering, sorting and paging.
### Filtering
The filter parameter accepts a list of semicolon-separated filters in the form: {fieldName}{operator}{fieldValue}
Filter terms within a single filter parameter are joined by a logical AND. 
Separate filter parameters are joined by a logical OR.
#### Operators
| Operator   | Meaning  |
| ----- | -------- |
| == | Exact match |
| != | Not equal |
| &lt;  | Less than |
| &lt;= | Less than or equal |
| &gt;  | Greater than |
| &gt;= | Greater than or equal |
| ~  | Matches string, supports wildcard characters * and ? |
| !~ | Not like, supports wildcard characters * and ? |

Examples: 

| URI   | Results  |
| ----- | -------- |
| GET /v1/users?filter=lastName==Doe;firstName==John | Users with firstName of 'John' AND lastName of 'Doe'. |
| GET /v1/users?filter=firstName==John;lastName=Doe&filter=firstName==Bob | Users with: (firstName of 'John' AND lastName of 'Doe') OR firstName of 'Bob'. |
| GET /v1/users?filter=location.cityName==Portland | Users with a city of 'Portland'. |
| GET /v1/users?filter=customAttributes.internalId==12345 | Users with a custom attribute of internalId equal to 12345'. |
| GET /v1/users?filter=lastInferredLocation.stateName==Georgia | Users with a last inferred location.stateName value of Georgia'. |
| GET /v1/users?filter=lastVisitedUserAgentData.userAgent.browserType==firefox | Users with firefox as last visited browser across the products '. |
| GET /v1/users?filter=lastVisitedUserAgentData.userAgent.browserType==firefox;lastVisitedUserAgentData.propertyKey==AP-8MF5LPSWUBFW-2 | Users with firefox as last visited browser for a particular product(with property key AP-8MF5LPSWUBFW-2)'. |

#### Supported filter fields for last inferred location
| Field   |
| ----- |
| lastInferredLocation.countryCode |
| lastInferredLocation.countryName |
| lastInferredLocation.stateCode |
| lastInferredLocation.stateName |
| lastInferredLocation.city |
| lastInferredLocation.continent |
| lastInferredLocation.postalCode |
| lastInferredLocation.regionName |
| lastInferredLocation.timeZone |
| lastInferredLocation.street |


### Sorting
The sort parameter accepts a list of semi-colon separated fields names, each with an optional dash to imply descending sort order.
Examples: 

| URI   | Results  |
| ----- | -------- |
| GET /v1/users?sort=lastName;firstName | Users sorted by firstName, lastName, in ascending order. |
| GET /v1/users?sort=-createDate | Users sorted by createDate in descending order. |

## Query parameters

- `filter` string[]
- `pageSize` integer
- `scrollId` string
- `sort` string

## Response `200`

Success

- UsersPage
  - `users` User[]: Array of users
    - `aptrinsicId` string
    - `identifyId` string, required
    - `type` 'LEAD' | 'USER' | 'VISITOR' | 'EMPTY_USER_TYPE'
    - `gender` 'MALE' | 'FEMALE' | 'OTHER' | 'EMPTY_GENDER'
    - `email` string
    - `firstName` string
    - `lastName` string
    - `lastSeenDate` integer
    - `signUpDate` integer
    - `firstVisitDate` integer
    - `title` string
    - `phone` string
    - `score` integer
    - `role` string
    - `subscriptionId` string
    - `accountId` string
    - `numberOfVisits` integer
    - `location` Location: Location object
      - `countryName` string
      - `countryCode` string: See ISO 3166
      - `stateName` string
      - `stateCode` string: See ISO 3166
      - `city` string
      - `street` string
      - `postalCode` string
      - `continent` string: See ISO 3166
      - `regionName` string: See ISO 3166-2
      - `timeZone` string
      - `coordinates` Coordinates: Coordinates object
        - `latitude` number, double
        - `longitude` number, double
    - `propertyKeys` string[], required: Aptrinsic Tag Key, at least one is required
    - `createDate` integer
    - `lastModifiedDate` integer
    - `customAttributes` object: Map of apiName to value
    - `globalUnsubscribe` boolean
    - `sfdcContactId` string
    - `channelMetricList` ChannelMetric[]
      - `groupId` string
      - `channel` integer
      - `environment` integer
      - `firstSeenDate` integer
      - `lastSeenDate` integer
    - `lastVisitedUserAgentData` UserAgentByProduct[]
      - `propertyKey` string
      - `userAgent` UserAgent: User Agent object
        - `rawUserAgent` string
        - `device` string
        - `platformType` string
        - `platformVersion` string
        - `browserType` string
        - `browserVersion` string
    - `id` string: Synonym for identifyId, output only, not filterable
    - `lastInferredLocation` Location: Location object
      - `countryName` string
      - `countryCode` string: See ISO 3166
      - `stateName` string
      - `stateCode` string: See ISO 3166
      - `city` string
      - `street` string
      - `postalCode` string
      - `continent` string: See ISO 3166
      - `regionName` string: See ISO 3166-2
      - `timeZone` string
      - `coordinates` Coordinates: Coordinates object
        - `latitude` number, double
        - `longitude` number, double
    - `globalId` string: Global user ID, only applicable for workspace-enabled subscriptions
  - `totalHits` integer: Total number of records matching filters
  - `scrollId` string: If passed on subsequent requests as the scrollId parameter, will fetch the next page

## Other responses

- `400`: Bad request
- `401`: Unauthorized or bad API Key
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/gainsight/apis/gainsight-px-rest-api.md) - [All operations](https://skmtc.dev/gainsight/apis/gainsight-px-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gainsight/apis/gainsight-px-rest-api/revisions/e7b197b373d8?raw)