[GET] - Contact Search

  • Updated

Use the Contacts Search endpoint to fetch a list of contacts.

The elements in the contacts list contain an id value and enough additional information such that a user could narrow down a selection from the list. Using the selected id values, you can retrieve additional contact information through the Contact Details endpoint.

Note: Please use filters to limit the list size to below 100K per API call.

Endpoint

GET https://api.insideview.com/api/v1/contacts

Request

HTTP Headers

Header Name Type Required Description
accessToken String Yes

Valid access token.
See Authentication and Authorization Overview for more details.
Accept String No Selects the response's content type.  
Valid values are application/json and application/xml (default).

Query Parameters

Parameter Name Type Required Description
email String Yes1 Contact email
lastName String Yes1 Contact last name
firstName String No Contact first name
middleName String No Contact middle name
fullName String Yes1 Contact Full Name 
country String No Country name (e.g. United States, France) for company search
state String No State name for company search
city String No City Name of company search
zip String No Zip code for company search
peopleCountries String No Comma separated list of Country Ids
peopleStates String No Comma separated list of States
peopleCities String No Comma separated list of Cities
peopleArea String No Area for the search
peopleAddress String No Address for the search
companyId Integer No Contact current Company Id
companyName String No Contact current Company Name
companyWebsite String No Contact current Company website (Only as Relevence filter)
active String No  If present will return only active or inactive records, depending on the value (true or false)
isEmailRequired String No If present and equals to true, the API will return only contact having an email address. 
isPhoneRequired String No If present and equals to true, the API will return only contact having a phone number.
emailValidationStatus String  No  It allows you to retrieve the validation status of the email. You can enter a comma-separated string with possible values i.e. ValidDomain and ValidEmail. 
minContactConfidenceScore String  No   The minimum contact confidence score. The valid values range from 0 to 100. 
maxContactConfidenceScore String  No The maximum contact confidence score. The valid values range from 0 to 100.  
page Integer No The page number of the result-set to return.
Default: 1
resultsPerPage Integer No The number of results in a page request.
Min: 1, Max: 50, Default: 10
phoneType String No

Accepts DIRECT, CORP, MOBILE, and ANY to find the corresponding contact's phone numbers.

Note: The Direct phone number is only available for InsideView customers and not OEM partners.

Mobile phone numbers are now available via the InsideView APIs for customers and partners who have purchased Elite or the mobile phone add-on to Enterprise license.
titles String No Return the job titles of an executive.

1: the request should include at least one of the two mandatory parameters.

Responses

HTTP 200

Returns either a JSON or XML data structure depending on the request Accept header. 

Name type Description
contacts Array  Array of search results
contacts firstName String Contact's first name
contacts middleName String  Contact's middle name
contacts lastName String  Contact's last name
contacts contactId String  InsideView Contact ID 
contacts companyId Integer Contact's InsideView Company ID
contacts companyName String Contact's company name
contacts titles List List of titles (String)
contacts active Boolean Active / inactive employment flag
contacts hasEmail Boolean True if the contact has an email address
contacts hasPhone Boolean True if the contact has a phone number
contacts peopleId String Return People Id
page Integer Page number in the result set
resultsPerPage Integer Number of search results per page
totalResults Integer Total number of search results
phoneType String Returns CORPORATE, DIRECT, and MOBILE phone number of an executive.
titles String Title of an executive

 

Type: application/json

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "/",
  "type": "object",
  "properties": {
    "totalResults": {
      "id": "totalResults",
      "type": "integer"
    },
    "page": {
      "id": "page",
      "type": "integer"
    },
    "resultsPerPage": {
      "id": "resultsPerPage",
      "type": "integer"
    },
    "contacts": {
      "id": "contacts",
      "type": "array",
      "items": [
        {
          "id": "0",
          "type": "object",
          "properties": {
            "firstName": {
              "id": "firstName",
              "type": "string"
            },
            "middleName": {
              "id": "middleName",
              "type": "string"
            },
            "lastName": {
              "id": "lastName",
              "type": "string"
            },
            "contactId": {
              "id": "contactId",
              "type": "integer"
            },
            "companyId": {
              "id": "companyId",
              "type": "integer"
            },
            "companyName": {
              "id": "companyName",
              "type": "string"
            },
            "titles": {
              "id": "titles",
              "type": "array",
              "items": {
                "id": "0",
                "type": "string"
              }
            },
            "active": {
              "id": "active",
              "type": "boolean"
            },
            "hasEmail": {
              "id": "hasEmail",
              "type": "boolean"
            },
            "hasPhone": {
              "id": "hasPhone",
              "type": "boolean"
            },
            "peopleId": {
              "id": "peopleId",
              "type": "string"
            },
            "confidenceScore": {
              "id": "confidenceScore",
              "type": "number"
            },
            "phoneType": {
              "id": "phoneType",
              "type": "string"
            }
          }
        }
      ]
    }
  }
}

Example

{
  "totalResults": 9226,
  "page": 1,
  "resultsPerPage": 10,
  "contacts": [
    {
      "firstName": "Tim",
      "lastName": "Cook",
      "contactId": 102100,
      "companyId": 726489,
      "companyName": "NIKE, Inc.",
      "titles": [
        "Independent Director"
      ],
      "active": true,
      "hasEmail": false,
      "hasPhone": true,
      "peopleId": "ZWUf25_lqO7SY_AEoCa9H23wj0W_7eCqHbJO3nw_7gcFrg2vQ0LZ2iS0pCse8MlD",
      "confidenceScore": 0.82,
      "phoneType": "DIRECT"
    },
    {
      "firstName": "Tim",
      "lastName": "Cook",
      "contactId": 11715849,
      "companyId": 29795,
      "companyName": "The National Football Foundation and College Hall of Fame, Inc.",
      "titles": [
        "Board Member"
      ],
      "active": true,
      "hasEmail": true,
      "hasPhone": true,
      "peopleId": "ZWUf25_lqO7SY_AEoCa9H23wj0W_7eCqHbJO3nw_7gcFrg2vQ0LZ2iS0pCse8MlD",
      "confidenceScore": 0.81,
      "phoneType": "CORP"
    },
    {
      "firstName": "Tim",
      "lastName": "Cook",
      "contactId": 11618410,
      "companyId": 861138,
      "companyName": "Hays plc",
      "titles": [
        "Global Head Digital & Business Innovation"
      ],
      "active": true,
      "hasEmail": true,
      "hasPhone": true,
      "peopleId": "6Kt1XlclfGkwwkQ5PIESSa6IwvagEoUFdTMkTanniLAp11t-vMIB0pNvSa2i8HBj",
      "confidenceScore": 0.83,
      "phoneType": "DIRECT"
    },
    {
      "firstName": "Tim",
      "lastName": "Cook",
      "contactId": 19762356,
      "companyId": 228533,
      "companyName": "Katz Sapper & Miller LLP",
      "titles": [
        "Partner"
      ],
      "active": true,
      "hasEmail": true,
      "hasPhone": false,
      "peopleId": "ewp__T0qXfw_9mDh2b4af2AJyysiFafbKteOceN8Bn3ViETFx0VUAmQFGXQbuUD4",
      "confidenceScore": 0.84
    },
    {
      "firstName": "Tim",
      "middleName": "",
      "lastName": "Cook",
      "contactId": 11855147,
      "companyId": 868732,
      "companyName": "MarketSense, LLC",
      "titles": [
        "Co President and Director of Client Services"
      ],
      "active": true,
      "hasEmail": true,
      "hasPhone": false,
      "peopleId": "6Kt1XlclfGkwwkQ5PIESSaKtduQMjyWgAin-n2fFq6Yb6pCw6jwwK0V3AiSvCVYg",
      "confidenceScore": 0.87
    },
    {
      "firstName": "Mr. Tim",
      "middleName": "J.",
      "lastName": "Cook",
      "contactId": 12678517,
      "companyId": 828560,
      "companyName": "Veritas Investments Ltd",
      "titles": [
        "Independent Chairman of the Board"
      ],
      "active": true,
      "hasEmail": false,
      "hasPhone": true,
      "peopleId": "hNJOWB49C8qt_aIU2nRI17WPbSPDHq2-hIReHuvJ_cAp811WBUKo5OcFmo-kwNKx",
      "confidenceScore": 0.8,
      "phoneType": "CORP"
    },
    {
      "firstName": "Tim",
      "middleName": "",
      "lastName": "Cook",
      "contactId": 16168192,
      "companyId": 738262,
      "companyName": "Enlivant",
      "titles": [
        "Senior Vice President of East Division"
      ],
      "active": true,
      "hasEmail": true,
      "hasPhone": false,
      "peopleId": "84OKnj1c07bdsDwj8_O4ZJQEwQXk0NH_JYGWOb9aPzLLHKzsyVe7zvVvCrPVbFCS",
      "confidenceScore": 0.85
    },
    {
      "firstName": "Tim",
      "lastName": "Cook",
      "contactId": 9081629,
      "companyId": 16451,
      "companyName": "Oxford Gene Technology IP Limited",
      "titles": [
        "Non-Executive Director"
      ],
      "active": true,
      "hasEmail": true,
      "hasPhone": false,
      "peopleId": "QDi0k2FHovaLby53gzAstbrnpUYgO1o8virSRnh8tEI11aPRmnF_2bSsscuk__wN",
      "confidenceScore": 0.81
    },
    {
      "firstName": "Tim",
      "lastName": "Cook",
      "contactId": 12035783,
      "companyId": 3418306,
      "companyName": "Independent Healthcare Properties, LLC",
      "titles": [
        "Vice President of Marketing and Regional Operations"
      ],
      "active": true,
      "hasEmail": false,
      "hasPhone": true,
      "peopleId": "RtAQCfBKDqHDOghtle5Wm7Ztm5jHBW4-cAtDahWHAGXPM-zBQ16pGmoIEBjw16Kq",
      "confidenceScore": 0.82,
      "phoneType": "DIRECT"
    },
    {
      "firstName": "Tim",
      "middleName": "",
      "lastName": "Cook",
      "contactId": 16066772,
      "companyId": 14764,
      "companyName": "San Diego Christian College",
      "titles": [
        "Head Coach Men's Basketball"
      ],
      "active": true,
      "hasEmail": true,
      "hasPhone": true,
      "peopleId": "1WhHImR7pXLvHsM8ffnIoTdKvozzTT9-n9-9XLXzQ3Uoj163AWobl2Zy6Z9VAspC",
      "confidenceScore": 0.8,
      "phoneType": "CORP"
    }
  ]
}

Type: application/xml

Schema: 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="contacts">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="contact" minOccurs="0" maxOccurs="unbounded">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="active" type="xs:string" />
                            <xs:element name="companyId" type="xs:int"/>
                            <xs:element name="companyName" type="xs:string" />
                            <xs:element name="confidenceScore" type="xs:decimal" minOccurs="0"/>
                            <xs:element name="contactId" type="xs:int"/>
                            <xs:element name="firstName" type="xs:string" minOccurs="0"/>
                            <xs:element name="hasEmail" type="xs:boolean" />
                            <xs:element name="hasPhone" type="xs:boolean"/>
                            <xs:element name="lastName" type="xs:string" minOccurs="0"/>
                            <xs:element name="middleName" type="xs:string" minOccurs="0"/>
                            <xs:element name="peopleId" type="xs:string"/>
                            <xs:element name="titles" type="xs:string" minOccurs="0"/>
                            <xs:element name="phoneType" type="xs:string"/>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
                <xs:element name="page" type="xs:int" minOccurs="0"/>
                <xs:element name="resultsPerPage" type="xs:int" minOccurs="0"/>
                <xs:element name="totalResults" type="xs:int" minOccurs="0"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

Example: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<contacts>
    <contact>
        <active>true</active>
        <companyId>726489</companyId>
        <companyName>NIKE, Inc.</companyName>
        <confidenceScore>0.82</confidenceScore>
        <contactId>102100</contactId>
        <firstName>Tim</firstName>
        <hasEmail>false</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <peopleId>ZWUf25_lqO7SY_AEoCa9H23wj0W_7eCqHbJO3nw_7gcFrg2vQ0LZ2iS0pCse8MlD</peopleId>
        <titles>Independent Director</titles>
        <phoneType>CORP</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>29795</companyId>
        <companyName>The National Football Foundation and College Hall of Fame, Inc.</companyName>
        <confidenceScore>0.81</confidenceScore>
        <contactId>11715849</contactId>
        <firstName>Tim</firstName>
        <hasEmail>true</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <peopleId>ZWUf25_lqO7SY_AEoCa9H23wj0W_7eCqHbJO3nw_7gcFrg2vQ0LZ2iS0pCse8MlD</peopleId>
        <titles>Board Member</titles>
        <phoneType>DIRECT</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>861138</companyId>
        <companyName>Hays plc</companyName>
        <confidenceScore>0.83</confidenceScore>
        <contactId>11618410</contactId>
        <firstName>Tim</firstName>
        <hasEmail>true</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <peopleId>6Kt1XlclfGkwwkQ5PIESSa6IwvagEoUFdTMkTanniLAp11t-vMIB0pNvSa2i8HBj</peopleId>
        <titles>Global Head Digital &amp; Business Innovation</titles>
        <phoneType>DIRECT</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>228533</companyId>
        <companyName>Katz Sapper &amp; Miller LLP</companyName>
        <confidenceScore>0.84</confidenceScore>
        <contactId>19762356</contactId>
        <firstName>Tim</firstName>
        <hasEmail>true</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <peopleId>ewp__T0qXfw_9mDh2b4af2AJyysiFafbKteOceN8Bn3ViETFx0VUAmQFGXQbuUD4</peopleId>
        <titles>Partner</titles>
        <phoneType>CORP</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>868732</companyId>
        <companyName>MarketSense, LLC</companyName>
        <confidenceScore>0.87</confidenceScore>
        <contactId>11855147</contactId>
        <firstName>Tim</firstName>
        <hasEmail>true</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <middleName></middleName>
        <peopleId>6Kt1XlclfGkwwkQ5PIESSaKtduQMjyWgAin-n2fFq6Yb6pCw6jwwK0V3AiSvCVYg</peopleId>
        <titles>Co President and Director of Client Services</titles>
        <phoneType>CORP</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>828560</companyId>
        <companyName>Veritas Investments Ltd</companyName>
        <confidenceScore>0.8</confidenceScore>
        <contactId>12678517</contactId>
        <firstName>Mr. Tim</firstName>
        <hasEmail>false</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <middleName>J.</middleName>
        <peopleId>hNJOWB49C8qt_aIU2nRI17WPbSPDHq2-hIReHuvJ_cAp811WBUKo5OcFmo-kwNKx</peopleId>
        <titles>Independent Chairman of the Board</titles>
        <phoneType>CORP</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>738262</companyId>
        <companyName>Enlivant</companyName>
        <confidenceScore>0.85</confidenceScore>
        <contactId>16168192</contactId>
        <firstName>Tim</firstName>
        <hasEmail>true</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <middleName></middleName>
        <peopleId>84OKnj1c07bdsDwj8_O4ZJQEwQXk0NH_JYGWOb9aPzLLHKzsyVe7zvVvCrPVbFCS</peopleId>
        <titles>Senior Vice President of East Division</titles>
        <phoneType>DIRECT</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>16451</companyId>
        <companyName>Oxford Gene Technology IP Limited</companyName>
        <confidenceScore>0.81</confidenceScore>
        <contactId>9081629</contactId>
        <firstName>Tim</firstName>
        <hasEmail>true</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <peopleId>QDi0k2FHovaLby53gzAstbrnpUYgO1o8virSRnh8tEI11aPRmnF_2bSsscuk__wN</peopleId>
        <titles>Non-Executive Director</titles>
        <phoneType>CORP</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>3418306</companyId>
        <companyName>Independent Healthcare Properties, LLC</companyName>
        <confidenceScore>0.82</confidenceScore>
        <contactId>12035783</contactId>
        <firstName>Tim</firstName>
        <hasEmail>false</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <peopleId>RtAQCfBKDqHDOghtle5Wm7Ztm5jHBW4-cAtDahWHAGXPM-zBQ16pGmoIEBjw16Kq</peopleId>
        <titles>Vice President of Marketing and Regional Operations</titles>
        <phoneType>DIRECT</phoneType>
    </contact>
    <contact>
        <active>true</active>
        <companyId>14764</companyId>
        <companyName>San Diego Christian College</companyName>
        <confidenceScore>0.8</confidenceScore>
        <contactId>16066772</contactId>
        <firstName>Tim</firstName>
        <hasEmail>true</hasEmail>
        <hasPhone>true</hasPhone>
        <lastName>Cook</lastName>
        <middleName></middleName>
        <peopleId>1WhHImR7pXLvHsM8ffnIoTdKvozzTT9-n9-9XLXzQ3Uoj163AWobl2Zy6Z9VAspC</peopleId>
        <titles>Head Coach Men's Basketball</titles>
        <phoneType>CORP</phoneType>
    </contact>
    <page>1</page>
    <resultsPerPage>10</resultsPerPage>
    <totalResults>9226</totalResults>
</contacts>

HTTP 400

Invalid query parameter(s).

HTTP 401

Unauthorized Error - Cannot use API's without setting a valid accessToken in header.

HTTP 405

Method Not Allowed - Your are not allowed to access this API.

HTTP 429

Request is throttled.