The Share Group

GraphQL API Additional Information

This document augments the operational instructions.

Verifying Connectivity to API:
To verify you have initial connectivity to the API (as well as verify the service is running), you can hit the following URL using a standard HTTP GET request:

   https://api.theshare.group/graphql/ping

    {"message": "pong"}

    curl https://api.theshare.group/graphql/ping -H "X-Api-Key: my_api_key"

Getting Data:
To make a request for data, use the following configuration:

Headers:

        "X-Api-Key": "your_api_key"
        "Content-Type": "application/json"
    

{ 
    "query": "query LookupAddress {lookupAddress(address: \"27623 NE Bradford Rd\", zip: \"98607\") {first, last}}"
}

Data Format:
The values for most fields are self-explanatory, however, some fields (such as date fields) require a specific format. Please use the following formats:

Field	Format	Example
All Date Fields	yyyy-mm-dd	2025-10-23
All Zip Code Radius Fields	Zip_Code-Radius. Radius is in miles and must be > 0.1	92203-3.5
date_of_name_mmyyyy	MMYYYY	062025

Best Practices:
Counts are Free:
Billing is based on user data returned. There is no charge to check if data is available (get a count). With this in mind, it is a good idea to first get a count of available records before retrieving the actual data.
Here is an example query to retrieve a count of all homes in zip code 92203 with a phone score of 1-5.:

    {
        "query": "query BlueprintCounts {blueprintCounts(blueprint: {name: \"dan_test\" data_source_id: 13 phones: all phone_type: wireless_priority phone_score: [\"1\", \"2\", \"3\", \"4\", \"5\"] filters: { field: \"zip\" values: \"92203\" condition: \"and\" } output_fields: \"\"}) {available}}"
    }
    

Phone Score:
Phone score is a rating from 1-6 that indicates the liklihood of the phone number being accurate. '1' is highest and '6' is the lowest. Our research has yielded the most accurate results using a score of 1-5.

Data Sources:
There are a number of data sources available with the most common being Consumer (#13) and Consumer Mortgage (#31). You can retrieve a list of all available data sources and the number of available records by making a call to the dataSources endpoint.

    {
        "query": "query dataSources {dataSources {id name size}}"
    }
    

        {
            "data": {
                "dataSources": [
                {
                    "id": 13,
                    "name": "Consumer",
                    "size": 269241053
                },
                {
                    "id": 15,
                    "name": "Auto",
                    "size": 222931866
                },
                ...
                ]
            }
        }        
    

    {
        "query": "query dataSource {dataSource(id: 13) {id name size fields{key range values{key value} } }}"
    }
    

Real World Example:

First, get the counts so you know if there is data available and so you limit the number of records returned if there are too many

        query Counts {
            blueprintCounts(
                blueprint: {
                    data_source_id: 13
                    phone_type: wireless_priority
                    filters: [
                        { field: "address", values: "86 Comet Rd", condition: "and" }
                        { field: "city", values: "Methuen", condition: "and" }
                        { field: "state", values: "MA", condition: "and" }
                    ]
                    output_fields: []
                }
            ) {
                available
            }
        }
    

Second, make a request to create the list. In the ‘recordCount’ field, specify the number of records you want returned. This will return the list ID which is used later in the next step.

        mutation CreateCustomList {
            createCustomList(
                blueprint: {
                    name: "dan_test"
                    data_source_id: 13
                    phone_type: wireless_priority
                    filters: [
                        { field: "address", values: "86 Comet Rd", condition: "and" }
                        { field: "city", values: "Methuen", condition: "and" }
                        { field: "state", values: "MA", condition: "and" }
                    ]
                    output_fields: ["firstName", "lastName"]
                }
                recordCount: 1
            ) {
                id
                name
                status
                recordCount
                fileURL
                createdAt
                updatedAt
            }
        }        
    

Finally, call the get list periodically (using the List ID from the previous step) until the list is available. The list is available when the 'status' == "ready" and at this point the 'fileURL' field will contain a download link.

        query List {
            list(id: 24225) {
                id
                name
                status
                recordCount
                fileURL
                createdAt
                updatedAt
            }
        }
    

Lookup Endpoints:

If you are only interested in a small number of records (e.x., for a specific address), the Lookup endpoints are ideal. They allow you to return a few records immediately as opposed to creating a full list. You can do a Lookup Count which will return a count of the number of results found or a plain Lookup which will return the actual records. As mentioned previously, counts are free so if you want to avoid fees you can do a count first to see if data is available and then request the data. There are dedicated endpoints for conducting searches by Address, Phone, Email or Person's Name. Additionally, there is a generic lookup endpoint where you can specify any crit

Retrieve a count:

            query LookupAddressCount {
                lookupAddressCount(address: "4726 French St", zip: "32205") {
                    available
                }
            }
        

Retrieve the record:

        query LookupAddress {
            lookupAddress(address: "4726 French St", zip: "32205", state: null) {
                first
                middle
                last
                address
                city
                state
                zip
                phone
            }
        }
    

Create a more complex lookup:

In this example, we are doing the same search by address, however, we've added criteria to ensure the record returned record is not a renter.

        query Lookup {
            lookup(lookup: { 
                            data_source_id: 13
                    select_type: "address_zip"
                    filters: [{
                                field: "address"
                                values: ["4726 French St"]
                                condition: "and"
                            },
                            {
                                field: "zip"
                                values: ["32205"]
                                condition: "and"
                            },
                            {
                                field: "homeowner"
                                values: ["R"]
                                condition: "and",
                                omit: true
                            }]
                    output_fields: []
             }) {
                first
                last
                phone
                lor
            }
        }