Rest api Contacts

Groundhogg provides the /contacts/ endpoint. The contacts endpoint allows users to query the contact table inside the  database and let you perform operations on contacts. This endpoint supports GET, POST, PUT, PATCH and DELETE HTTP operations. 

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 dropdown 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<br>
{
    "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 formate list for contact details.

http://yoursite.com/wp-json/gh/v3/contacts?select2=true<br>
{
    "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  contain  “Jhon” string in any of the contact details

{
    "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/v2/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
email 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  whos f irst name is John and lives in Canada.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us