Most IPQS APIs support multiple ways to submit data and authenticate your request. You can GET  using URL encoded parameters or POST  requests using JSON or multi-part form bodies.

Real-time (or synchronous) API calls that return data immediately support two distinct response formats: JSON and XML. Below are examples using each format. Note how the path changes in the callstring from json to xml to determine the response format that the API sends back. Response formats are defined in the URL call string and not in the request headers.

JSON

https://www.ipqualityscore.com/api/json/{API_NAME}/{API_KEY}/{LOOKUP_VALUE}

XML

https://www.ipqualityscore.com/api/xml/{API_NAME}/{API_KEY}/{LOOKUP_VALUE}

The next argument in the path defines the target API endpoint, such as the Proxy & VPN Detection API or the Email Verification API.

Common API Endpoints

• ip = Proxy & VPN Detection API
• email = Email Verification API
• phone = Phone Number Validation API
• url = Malicious URL Scanner API
• leaked = Dark Web Leak API
• malware = Malware File Scanner API

Examples

To call the Proxy & VPN Detection API, replace {API_NAME} with ip, as listed above:

https://www.ipqualityscore.com/api/json/ip/{API_KEY}/{LOOKUP_VALUE}

Similarly you would use email or phone for the Email Verification API and Phone Number Validation API, respectively:

https://www.ipqualityscore.com/api/json/email/{API_KEY}/{LOOKUP_VALUE}

https://www.ipqualityscore.com/api/json/phone/{API_KEY}/{LOOKUP_VALUE}

You will need to submit an API Key with your requests to authenticate with the API. You can create, edit, temporarily disable, and delete API Keys directly in the IPQS Dashboard.

You can pass API Keys in the path of the URL call string for GET and POST requests. In the example below, replace {API_KEY} with the API Key you created:

https://www.ipqualityscore.com/api/json/ip/{API_KEY}/{LOOKUP_VALUE}

You can also pass your API Key in the body of POST requests or the headers of GET and POST requests.

GET Requests

Pass the API Key in the path of the URL call string:

https://www.ipqualityscore.com/api/json/ip/{API_KEY}/{LOOKUP_VALUE}

You can also pass the API Key in the request headers, which is described in more detail below.

POST Requests

Pass the API Key in the body of the POST request as the value of key.

Multi-part Form Body Example

JSON Body Example

Headers

You can also pass the API Key in the request headers using either a multi-part form or JSON payload.

GET Request Example

POST Request Example

GET Requests

Passing parameters to the API as a GET request requires attaching parameters to the URL call string.

IP Address Example

https://www.ipqualityscore.com/api/json/ip/{API_KEY}/192.0.2.0

Email Address Example

Note how the email address does not need to be URL encoded because the email address is submitted in the path of the call string.

https://www.ipqualityscore.com/api/json/email/{API_KEY}/email@example.com

IP Address Example with Additional Parameters

Some APIs allow you to submit optional additional parameters to customize your API request. This example shows a request to the Proxy & VPN Detection API that includes the optional additional parameters of billing_address and billing_email, which are used in address validation. 

Note how the " " spaces in the billing address are URL encoded to %20 and the "@" symbol in the email address is URL encoded to %40 . This is because they must be URL encoded when passed as parameters. 

https://www.ipqualityscore.com/api/json/ip/{API_KEY}/192.0.2.0?billing_address=123%20west%20main%20st.&billing_email=email%40example.com

Header Example

POST Requests

Multi-part Form Body Example

JSON Body Example