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.

PARAM TYPE REQUIRED DESCRIPTION
query array no A query object, much like
the search object available
in the main Groundhogg search.
select bool no Whether to return a <select>
friendly response
select2 bool no Whether to return a select2
friendly response
search string no A simply search query
q string no Shorthand for search
id_or_email string | int no ID or email of a specific
contact to retrieve
by_user_id bool no If you are searching by the user ID
limit int no By default 100 records are returned.
offset int no By default starts at 0

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"
}
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