Rest API Contacts
Groundhogg provides the /contacts/ endpoint. The contacts endpoint allows users to query the contact table inside the
Listing Groundhogg Contacts
The GET method is used to get contacts from the database. Users can retrieve all the contacts from their database using the following query. Make sure to add header arguments while making API requests.
URL: http://yoursite.com/wp-json/gh/v3/contacts
{
"contacts": {
"1": {
"data": {
"email": "email@example.com",
"first_name": "Jhon",
"last_name": "Doe",
"user_id": "2",
"owner_id": "0",
"optin_status": "0",
"date_created": "2019-07-23 11:01:11",
"ID": "2",
"gravatar": "http:\/\/2.gravatar.com\/avatar\/eee931a46c043ad3b683e614b8c264f7?s=96&d=mm&r=g"
},
"meta": {
"preferences_changed": "1563894071",
"user_login": "test",
"profile_picture": "http:\/\/2.gravatar.com\/avatar\/eee931a46c043ad3b683e614b8c264f7?s=96&d=mm&r=g",
"primary_phone": "123456789",
"company_name": "Groundhogg",
"company_address": " 25 Lesmill Rd Unit D",
"street_address_1": " 25 Lesmill Rd Unit D",
"city": "North York",
"postal_zip": " M3B 2T3",
"region": "On",
"country": "CA"
},
"tags": [
11,
9,
2
],
"files": []
},
"2": {
...
},
"3": {
...
}
}
}<br>
List of contacts for select
Users can easily bound all the available contacts in drop down by setting select parameter true. It will return a list of contact ids and contact’s full name with the email address of a contact.
http://yoursite.com/wp-json/gh/v3/contacts?select=true
{
"contacts":{
"1":"Jhon Doe (Jhon@example.com)",
"2":"Doe Jhon (doe@example.com)"
},
"status":"success"
}
List of contacts for select2
Users can also bound contacts inside a select-2 drop down by setting select2=true while making GET requests. It will return the select2 format list for contact details.
http://yoursite.com/wp-json/gh/v3/contacts?select2=true
{
"results": [
{
"id": "1",
"text": "Jhon Doe (Jhon@example.com)"
},
{
"id": "2",
"text": "Doe Jhon (Doe@example.com)"
}
],
"more":false
}
Searching Contacts
Users can search for specific contact details by adding the argument “q” while making a request. Apart from that users can also add an array of query arguments while making a request to filter results.
You can also perform this operation by setting “id_or_email” to the user id of the user and passing by_user_id = true.
<code>http://yoursite.com/wp-json/gh/v3/contacts?q=jhon
This query will return all the contacts which
{
"contacts": {
"1": {
"data": {
"email": "email@example.com",
"first_name": "Jhon",
"last_name": "Doe",
"user_id": "2",
"owner_id": "0",
"optin_status": "0",
"date_created": "2019-07-23 11:01:11",
"ID": "2",
"gravatar": "http:\/\/2.gravatar.com\/avatar\/eee931a46c043ad3b683e614b8c264f7?s=96&d=mm&r=g"
},
"meta": {
"preferences_changed": "1563894071",
"user_login": "test",
"profile_picture": "http:\/\/2.gravatar.com\/avatar\/eee931a46c043ad3b683e614b8c264f7?s=96&d=mm&r=g",
"primary_phone": "123456789",
"company_name": "Groundhogg",
"company_address": " 25 Lesmill Rd Unit D",
"street_address_1": " 25 Lesmill Rd Unit D",
"city": "North York",
"postal_zip": " M3B 2T3",
"region": "On",
"country": "CA"
},
"tags": [
11,
9,
2
],
"files": []
},
"2": {
...
}
}
}<br>
Advanced Contact Search
Groundhogg provides search functionality where you can search contacts by proving various arguments.
You can search contacts by passing id_or_email, email, first_name, last_name, optin_status, owner, user_id in the URL.
http://yoursite.com/wp-json/gh/v3/contacts
You can also generate an advanced query by passing a JSON array as an argument in the HTTP request body, You need to use a query attribute to perform this operation and you can add the following params to your query.
| PARAM | DESCRIPTION | DEFAULT |
| number | The number of contacts you wish to retrieve. | -1 |
| offset | You can set offset the results using this argument. Default is 0. | 0 |
| orderby | The field you want to use to order the contacts. | ID |
| order | ASC or DESC | DESC |
| include | Any specific IDs which you want to include | null |
| exclude | Any IDs you wish to exclude | null |
| users_include | Include contacts with the associated USER IDs | null |
| users_exclude | Exclude contacts with the associated USER IDs | null |
| tags_include | Include contacts with the associated tags | null |
| tags_exclude | Exclude contacts with the associated tags | null |
| optin_status | Select contacts with the provided optin status. Accepts 0-6 or an array of optin status. | null |
| owner | Include contacts with the given owner ID | null |
| Select contacts with the given email address. (Will only ever return a single contact) | null | |
| first_name | Select contacts with the given first_name | null |
| last_name | Select contacts with the given last name | null |
| search | A search string that can search all the columns provided by the below param. | ” |
| search_columns | An array of columns to search. | All |
| meta_key | Include contacts which have the following meta key, require meta_value. | ” |
| meta_value | Include contacts with the given meta value. requires meta_key | ” |
For example:
{
"query": {
"meta_key" : "country",
"meta_value" : "CA",
"first_name" : "John"
}
}
The above query will search all the contacts and return a list of contacts