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",
  },
}).then((res) => res.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 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. The total_count property in pagination returns the the total number of contacts in the database.

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

If we want to query for contacts 11 - 20, we would request page 2 with a query parameter.

        const response = await fetch("https://api.packagex.io/v1/contacts?page=2&limit=10", {
  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 11 - 20
const pagination = response.pagination; //the pagination object

Filter

You can filter contacts by location_id, address_hash, group_id, and metadata properties.

location_id - Add a PackageX location ID to filter all contacts in that location.
address_hash - Add a PackageX address hash to filter all contacts in that location.
group_id = Add a PackageX group ID to filter all contacts in that group. Multiple group IDs can be used at once by separating them with a comma.
metadata - contacts can be filtered by a specific metadata key-value pair. Only one key-value pair can be used at a time.
created_at - Filter contacts by the date they were created.
updated_at - Filter contacts by the date they were last updated.

        const response = await fetch("https://api.packagex.io/v1/contacts?location_id=loc_38dZWuxaRrRNPoPEXVxgf4", {
  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
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, email, created_at, updated_at, _relevance, _similarity. The last two are only applicable when doing a search
direction - The direction to sort. Available directions are: asc and desc

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

        const response = await fetch("https://api.packagex.io/v1/contacts?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 contacts = 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

search.name: the primary name of the contact
search.names: all the names of the contact, including primary, alternate and nicknames
search.email: the primary email of the contact
search.emails: all the emails of the contact, including primary and alternates
search.phone: the primary phone of the contact
search.phones: all the phones of the contact, including primary and alternates
search.groups: all the group names of the contact

search.id_number: the ID number of the contact
search.metadata: the custom metadata of the contact

To perform a general search, simply provide a string to search by using the search query param. The results will be order by the most relevant first. To perform a targeted search, or a mixture of targeted search and general search, or to use various modifiers to boost a particular field, refer to the general section on search, while using the searchable properties provided above

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.

We also provide a _searchV2 object that has a searchV2.scores property for scores and searchV2.contact property with all matches highlighted with <mark> handles; this object has the same structure as the contact object, except only those properties are present where there are highlights.

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/contacts?search=jamie%jonez", {
  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
// "_search": {
//   "name": "<mark>Jamie/mark> Jones",
//   "nickname": null,
//   "group_names": [],
//   "email": "<mark>jamie</mark>.jones@packagex.xyz",
//   "phone": null,
//   "id_number": null,
//   "relevance_score": 0.98,
//   "query": "jamie"
// }

Retrieve Contacts