Contacts

Retrieve Contacts

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

Retrieve Contact

GET `/v1/contacts/:contact`

Get a single contact using its id.

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

const contact = response.data;

List Contacts

Example

GET `/v1/contacts`

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

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

const contacts = 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 contacts 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.

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

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

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

const contacts = response.data; //the array of contacts 25 - 50
const pagination = response.pagination; //the pagination object

Filter

You can filter contacts by type, location, and child properties.

type - Set to "person" or "group" to filter between contact types.
location - Add the location ID to filter all contacts by a specific location.
child - Will retrieve all contacts that have the requested contact listed in their children.

You can use filters along with pagination to get more specific views of deliveries.

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

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

Search

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

Searchable Properties

id
type
name
phone
email
address.formatted_address
metadata

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 contact objects called _search which will have the matched text surrounded with <mark> handles.

Relevance Score

If you want to show a relevance score on the search, you're able to pass the include_score query parameter and set its value to something truthy like "true" or 1. The reason the score requires a second property is that it could add up to 10ms of extra time to the request.

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

const contact = response.data[0];
console.log(contact._search); //Special _search property

//Sample _search response
//
//   id: "contact_rEMzyCyxJzuBzN4LyurAJV",
// 	 name: "<mark>Jamie</mark> <mark>Jone</mark>s",
// 	 email: "<mark>jamie</mark>@packagex.xyz",
//   phone: null,
//   formatted_address: "500 7th Ave, Fl 10, New York, NY 10018, United States",
//   relevance_score: 0.9962163584864516,

Retrieve Contacts