Reference - IP Enrichment API

The IP Enrichment API provides a one-to-one IP match, retrieving up-to-date information on a unique IP.

Endpoint

The endpoint for the IP Enrichment API is https://api.peopledatalabs.com/v5/ip/enrich.

IP Enrichment API Access and Billing

When the IP Enrichment API finds a matching IP address, it returns the IP record along with an HTTP response code of 200. When it doesn't find a matching IP, it returns an HTTP response code of 404. We charge per match.

Requests

See Authentication and Requests sections to see all possible ways to input a request. We recommend using a JSON object to capture input parameters and will do so in the examples.

Rate Limiting

Our default limit for free customers is 100 per minute. Our default limit for paying customers is 1,000 per minute.

Input Parameters

📘

For more details, see Input Parameters - IP Enrichment API

You can also click on the individual parameter names in the table below to view more information on them.

Parameter NameDescriptionExample
ipThe IP address to enrich in IPv4 or IPv6 format.72.212.42.169
api_keyYour secret API key.

Note: You can also provide this in the request header instead, as shown on the Authentication page.

Additional Input Parameters

You are not required to use the following additional input parameters. They generally transform or control various aspects of the enrichment process (returning matches or formatting results).

Parameter NameDescriptionExample
return_ip_locationIP responses will not include location data for the IP by default. Setting return_ip_location to true will return IP specific location info.false
return_ip_metadataIP responses will not include metadata for the IP by default. Setting return_ip_metadata to true will return IP specific metadata.false
return_if_unmatchedSetting return_if_unmatched to true will return IP specific metadata or location regardless of a company match.false
return_personSetting return_person to true will return IP specific person fields.false
min_confidenceReturn a result only if it meets the minimum confidence threshold.high
prettyWhether the output should have human-readable indentation.false
titlecaseAll text in the API responses returns as lowercase by default. Setting titlecase to true will titlecase the data in 200 responses.false
updated_title_rolesSet to true to return the updated taxonomy for job_title_role and job_title_subrole along with the new job_title_class field.
Temporary parameter available from Oct 2024 - Feb 2024.
true

Output Response

We return in the API response the ip record along with a 200 HTTP response code. If we do not find a match, we return a 404 HTTP response code.

Response Fields

📘

For more details, see Output Response - IP Enrichment API

You can also click the field names in the table below to view more information on them.

FieldDescriptionType
statusThe response code. See a description of our error codes.Integer
dataThe information about the IP address from the ip input parameter. Any fields that do not contain data will have a null value.Object
data.ipInformation related to the IP address.Object
data.ip.addressThe matched IP address.String
data.ip.metadataPremium fields targeted towards identifying IPs as mobile or using hosting, proxy, tor, vpn, relay or other services. Also includes domain associated with ASN block if it exists.Object
data.ip.locationThe location associated with the IP address.Object
data.companyInformation related to the company associated with the IP address.Object
data.company.confidenceHow confident we are that the returned company is associated with requested IP. Will be one of the following options: very high, high, moderate, low, very low.Enum (String)
data.company.idThe PDL ID of the company associated with the IP address.String
data.company.websiteThe primary website of the company associated with the IP address.String
data.company.nameThe name of the company associated with the IP address.String
data.company.display_nameThe display name of the company associated with the IP address.String
data.company.locationThe location of the company's primary HQ associated with the IP address.Object
data.company.sizeThe self-reported size range of the company associated with the IP address.Enum (String)
data.company.industryThe self-reported industry of the company associated with the IP address.Enum (String)
data.company.inferred_revenueThe estimated annual revenue (in USD) of the company associated with the IP address.Enum (String)
data.company.employee_countThe current number of employees working at the company associated with the IP address.Integer (> 0)
data.company.tagsTags associated with the company associated with the IP address.Array [String]
data.person.confidenceHow confident we are that the returned person is associated with requested IP. Will be one of the following options: very high, high, moderate, low, very low.Enum (String)
data.person.job_title_sub_roleThe derived subrole of the person's current job title.Enum (String)
data.person.job_title_roleThe derived role of the person's current job title.Enum (String)
data.person.job_title_levelsThe derived level(s) of the person's current job titleArray [String]
data.dataset_versionThe release number for the current buildString

Full Example Response

The response from the IP Enrichment API will be in this format:

{
    "status": 200,
    "data": {
        "ip": {
            "address": "72.212.42.169",
            "metadata": {
                "version": 4,
                "mobile": false,
                "hosting": false,
                "proxy": false,
                "tor": false,
                "vpn": false,
                "relay": false,
                "service": null,
              	"asn_domain": null,
            },
            "location": {
                "name": "phoenix, arizona, united states",
                "locality": "phoenix",
                "region": "arizona",
                "metro": "phoenix, arizona",
                "country": "united states",
                "continent": "north america",
                "postal_code": "85001",
                "geo": "33.44838,-112.07404",
                "timezone": "america/phoenix"
            }
        },
        "company": {
            "confidence": "very high",
            "id": "tnHcNHbCv8MKeLh92946LAkX6PKg",
            "website": "peopledatalabs.com",
            "name": "people data labs",
            "display_name": "People Data Labs",
            "location": {
                "name": "san francisco, california, united states",
                "locality": "san francisco",
                "region": "california",
                "metro": "san francisco, california",
                "country": "united states",
                "continent": "north america",
                "street_address": "455 market street",
                "address_line_2": "suite 1670",
                "postal_code": "94105",
                "geo": "37.77,-122.41"
            },
            "size": "11-50",
            "industry": "computer software",
            "inferred_revenue": "$25m-$50m",
            "employee_count": 129,
            "tags": [
                "artificial intelligence",
                "data and analytics",
                "machine learning",
                "analytics",
                "database",
                "software",
                "developer apis",
                "data",
                "people data",
                "data science"
            ]
        },
      	"person": {
          	"confidence": "very high",
            "job_title_sub_role": "product",
            "job_title_role": "operations",
            "job_title_levels": [
                "cxo"
            ]
        },
      	"dataset_version": "1.1.0.2024w19"
    }
}

Errors

If the request encounters an error, it will instead return an Error Response in the format described in Errors.