REST API V3 / Contact / Get

URL

GET /wp-json/gh/v3/contacts

Method

This endpoint supports the GET method

Request

This endpoint provides multiple ways of searching and retrieving contact information. Here are the parameters you can specify.

query, search, q, id_or_email are exclusive, meaning if you are using one you may not use the

Query

Passing query is the most advanced search option, it uses the main search query available from the Groundhogg advanced search UI. For a full list of arguments see here.

Example Request

The below request will return anyone whos named John and has the tags with IDs 1, 2 or 3.

{
    "query": {
        "tags_include" : [ 1, 2, 3 ],
        "first_name" : "John"
    }
}

Example Response

You will receive a list of contacts with their full profiles and attributes.

{
    "contacts": {
        "1": {
            "data": {
                "email": "response@example.com",
                "first_name": "admin",
                "last_name": "",
                "user_id": 1,
                "owner_id": 0,
                "optin_status": 1,
                "date_created": "2020-06-11 18:02:16",
                "date_optin_status_changed": "2020-06-11 18:02:16",
                "ID": 1,
                "age": false
            },
            "meta": {
                "user_login": "admin",
                "times_logged_in": "1",
                "birthday": ""
            },
            "tags": [
                11
            ],
            "files": []
        }
    },
    "status": "success"
}

Search & Q

search and q perform the same function, q is just shorthand for search. The fields which are search are first_name, last_name, email, date_created.

Example Request

Return anyone who has a gmail.com email address.

{
    "search" : "@gmail.com"
}

Return anyone that has a hotmail.com address.

{
    "q" : "@hotmail.com",
}

Response

The same as passing query.

Getting Single Contacts

To retrieve a single contact record specifies the id_or_email parameter.

Example Request

{
    "id_or_email" : "email@example.com",
    "by_user_id" : false
}

Example Response

{
    "contact": {
        "ID": 5123,
        "data": {
            "email": "email@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "user_id": 1,
            "owner_id": 1,
            "optin_status": 1,
            "date_created": "2020-06-17 11:59:22",
            "date_optin_status_changed": "2020-06-17 11:59:22",
            "ID": 5123,
            "gravatar": "http://localhost/wordpress/wp-content/plugins/buddyboss-platform/bp-core/images/mystery-man.jpg",
            "age": false
        },
        "meta": {
            "primary_phone": "1234567890",
            "primary_phone_extension": "5623",
            "street_address_1": "1222 Mariners Rd",
            "street_address_2": "Unit D",
            "city": "Blenheim",
            "postal_zip": " 
   N0P 1A0",
            "region": "Ontario",
            "country": "CA",
            "lead_source": "",
            "source_page": "",
            "custom_meta": "this is meta",
            "profile_picture": "http://2.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e?s=300&d=mm&r=g",
            "birthday": ""
        },
        "tags": [
            17,
            16,
            9,
            2
        ],
        "files": []
    },
    "status": "success"
}