1. Users
  2. Retrieve Users

Users

Retrieve Users

Retrieve User

GET
`/v1/users/:user`

Get a single user using its id.

js 
        const response = await fetch(`https://api.packagex.io/v1/user/${user_id}`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const user = response.data;

List Users

Retrieve a list of users with comprehensive filtering, searching, and pagination capabilities. When you want to retrieve multiple users, your data property on the result will always be an array even if you don't have any users. The users are returned in alphabetical order by name. Two endpoint variations are available:

Standard List Endpoint

Provides detailed user information with pagination support.

GET
`/v1/users`
js 
        const response = await fetch(`https://api.packagex.io/v1/users`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const users = response.data;

Cached List Endpoint

Optimized for quick access to basic user data without pagination.

GET
`/v1/users?cache=1`
js 
        const response = await fetch(`https://api.packagex.io/v1/users?cache=1`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const users = response.data;

Query Parameters

Filtering

The API supports comprehensive filtering of users through query parameters. Multiple filters can be combined to refine your results.

Parameter Type Description
role_id or role string Filter users by role_id.
email string Filter users by email.
notification_event or event string Filter users by a specific notification event.
roles string Filter users by multiple role IDs.

Filtering Examples

  • Filter by role_id or role
js 
        const response = await fetch(`https://api.packagex.io/v1/users?role_id=abc123xyz`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const users = response.data;
const pagination = response.pagination;
  • Filter by email
js 
        const response = await fetch(`https://api.packagex.io/v1/users?email=john@packagex.xyz`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const users = response.data;
const pagination = response.pagination;

Pagination

The response includes a pagination object with the following properties:

  • has_more - Indicates if there are more users available
  • page - Current page number (default: 1)
  • limit - Number of results per page (default: 25)
  • total_count - Total number of users in the database.

To retrieve the next page of results:

js 
        const response = await fetch(`https://api.packagex.io/v1/users?page=1&limit=25`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  }
}).then((res) => res.json());

const users = response.data;
const pagination = response.pagination;

Sorting

Control the order of results using:

Parameter Type Default Description
order_by string created_at Field to sort by, supported values: name, created_at, updated_at
direction string asc Sort direction, supported values: asc, desc

If no sorting parameter is specified, the system defaults to sorting by name in ascending order asc

Example with sorting:

js 
        const response = await fetch(`https://api.packagex.io/v1/users?order_by=updated_at&direction=desc`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  }
}).then((res) => res.json());

const users = response.data;
const pagination = response.pagination;

The API provides advanced full-text search capabilities through the search parameter, allowing you to search users using fuzzy, typo-tolerant matching across multiple fields. The search functionality examines key user properties including:

  • name
  • email
js 
        const response = await fetch(`https://api.packagex.io/v1/users?search=John`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  }
}).then((res) => res.json());

const users = response.data;
const pagination = response.pagination;

Each user in the search results includes a special _search object that provides detailed information about the match:

js 
        "_search": {
  "name": "<mark>John</mark>",
  "email": "<mark>john</mark>@packagex.xyz",
  "relevance_score": 0.98,
  "query": "john"
}

The _search object includes highlighted matches using <mark> tags, making it easy to emphasize matching text in user interfaces. It also provides a relevance score between 0 and 1, where higher values indicate better matches. By default, search results are ordered by relevance score to show the best matches first. However, you can override this by specifying an order_by parameter to sort by other fields like created_at, updated_at, name. The search functionality can be combined with other filter parameters to refine your results further.

List User Notifications

Retrieve a list of notifications.

GET
`/v1/users/:user/notifications`
js 
        const response = await fetch(`https://api.packagex.io/v1/users/${user_id}/notifications`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const notifications = response.data;

Query Parameters

Filtering

Parameter Type Description
location_id or location string Filter notifications by location ID.

Filtering Examples

  • Filter by location_id or location
js 
        const response = await fetch(`https://api.packagex.io/v1/users/${user_id}/notifications`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const notifications = response.data;
const pagination = response.pagination;

Pagination

The response includes a pagination object with the following properties:

  • has_more - Indicates if there are more notifications available
  • page - Current page number (default: 1)
  • limit - Number of results per page (default: 25)
  • total_count - Total number of notifications in the database.

To retrieve the next page of results:

js 
        const response = await fetch(`https://api.packagex.io/v1/users/${user_id}/notifications?page=1&limit=25`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  }
}).then((res) => res.json());

const notifications = response.data;
const pagination = response.pagination;

Sorting

Control the order of results using:

Parameter Type Default Description
order_by string created_at Field to sort by.
direction string desc Sort direction, supported values: asc, desc

If no sorting parameter is specified, the system defaults to sorting by created_at in descending order desc

Example with sorting:

js 
        const response = await fetch(`https://api.packagex.io/v1/users/${user_id}/notifications?order_by=updated_at&direction=desc`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  }
}).then((res) => res.json());

const notifications = response.data;
const pagination = response.pagination;
Previous <- Write Users
Next Delete Users ->