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 ContactGET `/v1/contacts/:contact`
Get a single contact using its id
.
List Contacts
ExampleGET `/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.
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 contacts 26 - 50, we would request page 2 with a query parameter.
Filter
You can filter contacts by type
, address_hash
, and child
properties.
- type - Set to "person" or "group" to filter between contact types.
- address_hash - Add a PackageX address hash to filter all contacts in that location.
- child - Pass a contact ID here to retrieve all contacts that are a parent of the ID you have provided. Only contacts with the
type
set to "group" will have children.
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
- direction - The direction to sort. Available directions are:
asc
anddesc
By default, contacts will be sorted by name in ascending order.
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.