Submitting Data To IPQS APIs

Rate this article:

X

Select all that apply:

The content is confusing or hard to follow.

There is missing information or code.

There is inaccurate or outdated information.

This page did not solve my problem.

I would like to speak with someone about this.

Email:

Submit Feedback

About Submitting Data for Analysis

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.

Standard API Endpoint Request Format

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}

Defining API Endpoints

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}

Authorization - Passing Your API Key

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

curl --request POST \
  --url https://www.ipqualityscore.com/api/json/ip/ \
  --header 'content-type: multipart/form-data' \
  --form ip=192.0.2.0 \
  --form key={API_KEY} \

JSON Body Example

curl --request POST \
--url https://www.ipqualityscore.com/api/json/ip/ \
--header 'content-type: application/json' \
--data '{
"key": "{API_KEY}",
"ip": "192.0.2.0"
}'

Headers

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

GET Request Example

curl --request GET \
  --url 'https://www.ipqualityscore.com/api/json/ip?ip=192.0.2.0' \
  --header 'ipqs-key: {API_KEY}'

POST Request Example

curl --request POST \
  --url https://www.ipqualityscore.com/api/json/ip/ \
  --header 'content-type: application/json' \
  --header 'ipqs-key: {API_KEY}' \
  --data '{
  "ip": "192.0.2.0"
}'

Passing Parameters

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

curl --request GET \
  --url 'https://www.ipqualityscore.com/api/json/ip?ip=192.0.2.0' \
  --header 'ipqs-key: {API_KEY}'

POST Requests

Multi-part Form Body Example

curl --request POST \
  --url https://www.ipqualityscore.com/api/json/ip/ \
  --header 'content-type: multipart/form-data' \
  --form ip=192.0.2.0 \
  --form key={API_KEY} \
  --form 'billing_address=123 main st' \
  --form billing_city=anytown

JSON Body Example

curl --request POST \
  --url https://www.ipqualityscore.com/api/json/allowlist/create/ \
  --header 'content-type: text/plain' \
  --data '{
  "type": "proxy",
  "value_type": "ip",
  "value": "192.0.2.0",
  "reason": "example"
  "key":"{API_KEY}"
}'