> ## Documentation Index > Fetch the complete documentation index at: https://docs.peopledatalabs.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://docs.peopledatalabs.com/docs/authentication) and [Requests](https://docs.peopledatalabs.com/docs/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](https://docs.peopledatalabs.com/docs/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 Name Description Example
[`ip`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#ip) The IP address to enrich in IPv4 or IPv6 format. `72.212.42.169`
[`api_key`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#api_key) Your secret API key.

**Note**: You can also provide this in the request header instead, as shown on the [Authentication](https://docs.peopledatalabs.com/docs/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`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#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`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#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`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#return_if_unmatched) | Setting `return_if_unmatched` to `true` will return IP specific metadata or location regardless of a company match. | `false` | | [`return_person`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#return_person) | Setting `return_person` to `true` will return IP specific person fields. | `false` | | [`min_confidence`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#min_confidence) | Return a result only if it meets the minimum confidence threshold. | `high` | | [`pretty`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#pretty) | Whether the output should have [human-readable](http://jsonprettyprint.net/) indentation. | `false` | | [`titlecase`](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#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 API](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api) > > You can also click the field names in the table below to view more information on them. | Field | Description | Type | | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | [`status`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#status) | The response code. See a description of our [error codes](errors). | `Integer` | | [`data`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#data) | The information about the IP address from the [`ip` input parameter](https://docs.peopledatalabs.com/docs/input-parameters-ip-enrichment-api#ip). Any fields that do not contain data will have a `null` value. | `Object` | | [`data.ip`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#dataip) | Information related to the IP address. | `Object` | | [`data.ip.address`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#dataipaddress) | The matched IP address. | `String` | | [`data.ip.metadata`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#dataipmetadata) | 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`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#dataiplocation) | The location associated with the IP address. | `Object` | | [`data.company`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompany) | Information related to the company associated with the IP address. | `Object` | | [`data.company.confidence`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanyconfidence) | 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`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanyid) | The [PDL ID](https://docs.peopledatalabs.com/docs/company-schema#id) of the company associated with the IP address. | `String` | | [`data.company.website`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanywebsite) | The [primary website](https://docs.peopledatalabs.com/docs/company-schema#website) of the company associated with the IP address. | `String` | | [`data.company.name`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanyname) | The [name](https://docs.peopledatalabs.com/docs/company-schema#name) of the company associated with the IP address. | `String` | | [`data.company.display_name`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanydisplay_name) | The [display name](https://docs.peopledatalabs.com/docs/company-schema#display_name) of the company associated with the IP address. | `String` | | [`data.company.location`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanylocation) | The [location](https://docs.peopledatalabs.com/docs/company-schema#location) of the company's primary HQ associated with the IP address. | `Object` | | [`data.company.size`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanysize) | The self-reported [size range](https://docs.peopledatalabs.com/docs/company-sizes) of the company associated with the IP address. | `Enum (String)` | | [`data.company.industry`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanyindustry) | The self-reported [industry](https://docs.peopledatalabs.com/docs/industries) of the company associated with the IP address. | `Enum (String)` | | [`data.company.inferred_revenue`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanyinferred_revenue) | The [estimated annual revenue](https://docs.peopledatalabs.com/docs/inferred-revenue-ranges) (in USD) of the company associated with the IP address. | `Enum (String)` | | [`data.company.employee_count`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanyemployee_count) | The current [number of employees](https://docs.peopledatalabs.com/docs/company-schema#employee_count) working at the company associated with the IP address. | `Integer (> 0)` | | [`data.company.tags`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datacompanytags) | [Tags](https://docs.peopledatalabs.com/docs/company-schema#tags) associated with the company associated with the IP address. | `Array [String]` | | [`data.person.confidence`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datapersonconfidence) | 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`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datapersonjob_title_sub_role) | The derived [subrole](https://docs.peopledatalabs.com/docs/job-title-subroles) of the person's current job title. | `Enum (String)` | | [`data.person.job_title_role`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datapersonjob_title_role) | The derived [role](https://docs.peopledatalabs.com/docs/job-title-roles) of the person's current job title. | `Enum (String)` | | [`data.person.job_title_levels`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datapersonjob_title_levels) | The derived [level(s)](https://docs.peopledatalabs.com/docs/job-title-levels) of the person's current job title | `Array [String]` | | [`data.dataset_version`](https://docs.peopledatalabs.com/docs/output-response-ip-enrichment-api#datadataset_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](https://docs.peopledatalabs.com/docs/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. ```Text 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" } } } ```