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 APIYou can also click on the individual parameter names in the table below to view more information on them.

Parameter Name	Description	Example
`ip`	The IP address to enrich in IPv4 or IPv6 format.	`72.212.42.169`
`api_key`	Your 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 Name	Description	Example
`return_ip_location`	IP 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_metadata`	IP responses will not include metadata for the IP by default. Setting `return_ip_metadata` to `true` will return IP specific metadata.	`false`
`return_if_unmatched`	Setting `return_if_unmatched` to `true` will return IP specific metadata or location regardless of a company match.	`false`
`return_person`	Setting `return_person` to `true` will return IP specific person fields.	`false`
`min_confidence`	Return a result only if it meets the minimum confidence threshold.	`high`
`pretty`	Whether the output should have human-readable indentation.	`false`
`titlecase`	All text in the API responses returns as lowercase by default. Setting `titlecase` to `true` will titlecase the data in `200` responses.	`false`

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 APIYou can also click the field names in the table below to view more information on them.

Field	Description	Type
`status`	The response code. See a description of our error codes.	`Integer`
`data`	The information about the IP address from the `ip` input parameter. Any fields that do not contain data will have a `null` value.	`Object`
`data.ip`	Information related to the IP address.	`Object`
`data.ip.address`	The matched IP address.	`String`
`data.ip.metadata`	Premium 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.location`	The location associated with the IP address.	`Object`
`data.company`	Information related to the company associated with the IP address.	`Object`
`data.company.confidence`	How 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.id`	The PDL ID of the company associated with the IP address.	`String`
`data.company.website`	The primary website of the company associated with the IP address.	`String`
`data.company.name`	The name of the company associated with the IP address.	`String`
`data.company.display_name`	The display name of the company associated with the IP address.	`String`
`data.company.location`	The location of the company’s primary HQ associated with the IP address.	`Object`
`data.company.size`	The self-reported size range of the company associated with the IP address.	`Enum (String)`
`data.company.industry`	The self-reported industry of the company associated with the IP address.	`Enum (String)`
`data.company.inferred_revenue`	The estimated annual revenue (in USD) of the company associated with the IP address.	`Enum (String)`
`data.company.employee_count`	The current number of employees working at the company associated with the IP address.	`Integer (> 0)`
`data.company.tags`	Tags associated with the company associated with the IP address.	`Array [String]`
`data.person.confidence`	How 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_role`	The derived subrole of the person’s current job title.	`Enum (String)`
`data.person.job_title_role`	The derived role of the person’s current job title.	`Enum (String)`
`data.person.job_title_levels`	The derived level(s) of the person’s current job title	`Array [String]`
`data.dataset_version`	The release number for the current build	`String`

Full Example Response

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

JSON

{
    "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. In general, the error codes are ubiquitous across products with one exception. The IP Enrichment API will return a 400 in situations where the IP address is known to be a Hosting Provider, Proxy, Tor, Relay, or Service. These IP addresses cannot be resolved to a specific company.

JSON

{
    "status": 400,
    "error": "Cannot Enrich IP",
    "message": "IP is a Hosting Provider, Proxy, Tor, Relay, or Service",
    "data": {
        "ip": {
            "address": "54.81.251.238"
        }
    }
}

General

API Overview

Person Data

Person APIs

Company Data

Company APIs

IP Data

IP API

Job Posting Data

Job Posting API

Supporting APIs

Data Standardization

Free Datasets

Libraries

Integrations

Resources

Data License

Support

Reference - IP Enrichment API

Endpoint

IP Enrichment API Access and Billing

Requests

Rate Limiting

Input Parameters

Additional Input Parameters

Output Response

Response Fields

Full Example Response

Errors

​Endpoint

​IP Enrichment API Access and Billing

​Requests

​Rate Limiting

​Input Parameters

​Additional Input Parameters

​Output Response

​Response Fields

​Full Example Response

​Errors

Endpoint

IP Enrichment API Access and Billing

Requests

Rate Limiting

Input Parameters

Additional Input Parameters

Output Response

Response Fields

Full Example Response

Errors