Get All Users

The following table outlines the possible fields which can be expected in the API response.

Name	Type	Description
id	string	Validic user ID
uid	string	Customer’s user identifier.
marketplace > token		Unique marketplace identifier.
marketplace > url	string	The user’s marketplace URL. Requesting this URL with the ‘Accept’ header as ‘application/json’ will provide a JSON representation of the marketplace. Otherwise an HTML representation will be presented.
mobile > token	string	Unique identifier used to connect users to the Validic mobile solution.
location > timezone	string	Default user timezone. When retrieving data from a source that provides no UTC offset information the default timezone will be used to calculate the UTC offset.
location > country_code	string	User’s country identified as a two character country code using the ISO 3166-1 standard. Validic uses this information for integrations that provide data access based upon the user’s country.
created_at	string	The date and time the resource was created.
updated_at	string	The date and time the resource was updated.

Sorting and Filtering

The API supports the following sorting and filtering options:

Sort by descending: ?sort[]=-created_at
Sort by multiple fields: ?sort[]=created_at&sort[]=uid
Filter by field: ?q[]=uid=vpt12345sp
Filter by multiple fields: ?q[]=status=active&q[]=uid=vpt12345sp
Limit results: ?limit=number_of_results (default: 100, maximum: 1000)

Pagination Explained

This API uses the offset and limit parameters for pagination. It’s crucial to understand that offset does not represent page numbers or user counts directly but rather the page index.

Here's how it works:

Offset and Limit Calculation:
- A request with no offset (default offset=0) and limit=1000 returns the first 1000 users.
- A request with offset=1 and limit=1000 fetches the next 1000 users (users 1001–2000).
- Offset essentially represents the page index where each page contains the number of results defined by the limit parameter.
Iterating Through Users:
- To retrieve all users, increment the offset while keeping the limit fixed until you receive an empty response.
- For example:
  - Request: ?limit=1000&offset=0 → Returns users 1–1000.
  - Request: ?limit=1000&offset=1 → Returns users 1001–2000.
  - Continue incrementing the offset until you receive an empty object.
Important Notes:
- If the total number of users is less than the calculated offset (offset * limit), the API will return an empty object.
- The maximum value for limit is 1000. If no limit is specified, the default is 100.

Examples

Fetch the first 1000 users:

GET /users?limit=1000&offset=0

Fetch users 2001 to 3000:

GET /users?limit=1000&offset=2

Fetch all users (iterate until empty response):

// Start at offset 0 and continue until an empty response
GET /users?limit=1000&offset=0
GET /users?limit=1000&offset=1
GET /users?limit=1000&offset=2
...