Groups

Retrieve Groups

Retrieving a single group is pretty straightforward. You'll just use the id of the group to get it. When you are retrieving multiple groups, there are additional search and filter options available.

# Retrieve Group

Get a single group using its id.

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

const group = response.data;

      

# List Groups

# Example

When you want to retrieve multiple groups, your data property on the result will always be an array even if you don't have any groups. The groups are returned in alphabetical order by name.

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

const groups = response.data;
const pagination = response.pagination;

      

# Pagination

If the has_more property on the pagination object is set to true, you know there are more groups in the database that have not been returned to you. The pagination object also has a page property indicating your current offset and a limit property. The total_count property in pagination returns the the total number of groups in the database.

By default the page is set to 1 and the limit is 10.

If we want to query for groups 26 - 50, we would request page 2 with a query parameter.

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

const groups = response.data; //the array of groups 11 - 20
const pagination = response.pagination; //the pagination object

      

# Filter

You can filter groups by resource, location_id, and metadata properties.

• resource - Set to "contact" or "location" to filter.
• location_id - Add a PackageX location ID to filter all contacts in that location.
• metadata - Groups can be filtered by a specific metadata key-value pair. Only one key-value pair can be used at a time.

        const response = await fetch("https://api.packagex.io/v1/groups?type=contact&location_id=loc_38dZWuxaRrRNPoPEXVxgf4", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const groups = response.data; //the array of groups
const pagination = response.pagination; //the pagination object

      

# Sorting

Sorting describes in what order you want your responses to come in. You can select an available property by which to sort, as well as the direction.

• order_by - The property by which to sort. Available properties are: name, created_at, updated_at
• direction - The direction to sort. Available directions are: asc and desc

By default, groups will be sorted by name in ascending order.

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

const groups = response.data; //the array of groups
const pagination = response.pagination; //the pagination object

      

# Search

There are times when filtering is not enough and you want to find a specific group by some other attribute. In this case, you can do a fuzzy, typo-tolerant search of every group in the database. Below are the properties that are supported by our full text search.

Searchable Properties

• name

To search, simply provide a string to search by using the search query param. The results will be order by the most relevant first. If you want to highlight matching search results for a frontend, we provide a special property for search-returned group objects called _search which will have the matched text surrounded with <mark> handles.

Ordering Search Results

By default, search results are ordered by relevance. However, if you include an order_by parameter along with your search query, the results will be ordered by the specified property instead of by relevance.

Relevance Score

Relevance scores are included in the search results by default. Note that this could add up to 10ms of extra time to the request.

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

const group = response.data[0];
console.log(group._search);

// Special _search property
// "_search": {
//   "name": "<mark>Pack</mark>ageX Inc.",
//   "relevance_score": 0.93,
//   "query": "Pack"
// }