Services Endpoints
Use the references for REST API V9.0 services endpoints.
POST /services/dig_lookups
Creates a new DIG lookup. Lookup completes in the background.
Table 1: POST /services/dig_lookups Resource Details
MIME Type |
|---|
application/json |
Table 2: POST /services/dig_lookups Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
IP | query | Required | String | text/plain | Used to retrieve the DIG lookup. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 3: POST /services/dig_lookups Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
201 | The DIG lookup was created successfully. | |
500 | 1020 | An internal server error occurred during the creation of the DIG lookup. |
Response Description
A DIG Lookup object, and the location header that is set to the task status URL "/services/dig_lookups/{dig_lookup_id}". A DIG Lookup object contains the following fields:
id - Long - The ID of the DIG lookup.
ip - String - The IP address to be investigated.
message - String - The result of the DIG lookup when it is complete.
status - String - The current state of the task.
Response Sample
{ "id": 42, "ip": "String", "message": "String", "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }
GET /services/dig_lookups/{dig_lookup_id}
Retrieves the DIG Lookup status and result. The result is included if the lookup completed.
Table 4: GET /services/dig_lookups/{dig_lookup_id} Resource Details
MIME Type |
|---|
application/json |
Table 5: GET /services/dig_lookups/{dig_lookup_id} Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
dig_lookup_id | path | Required | Number (Integer) | text/plain | Required - The ID of the Dig lookup to be retrieved. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 6: GET /services/dig_lookups/{dig_lookup_id} Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
200 | The DIG lookup Status was retrieved. | |
404 | 1002 | The DIG lookup status does not exist. |
500 | 1020 | An error occurred during the attempt to retrieve the DIG lookup status. |
Response Description
A DIG Lookup object, and the location header that is set to the task status URL "/services/dig_lookups/{dig_lookup_id}". A DIG Lookup object contains the following fields:
id - Long - The ID of the DIG lookup.
ip - String - The IP address to be investigated.
message - String - The result of the DIG lookup when it is complete.
status - String - The current state of the task.
Response Sample
{ "id": 42, "ip": "String", "message": "String", "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }
POST /services/dns_lookups
Creates a new DNS lookup. Lookup completes in the background.
Table 7: POST /services/dns_lookups Resource Details
MIME Type |
|---|
application/json |
Table 8: POST /services/dns_lookups Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
IP | query | Required | String | text/plain | Used to retrieve the DNS lookup. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 9: POST /services/dns_lookups Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
201 | The DNS lookup was successfully created. | |
500 | 1020 | An internal server error occurred during the creation of the DNS lookup. |
Response Description
A DNS Lookup object and the location header set to the task status URL "/services/dns_lookups/{dns_lookup_id}". A DNS status object contains the following fields:
id - Long - The ID of the DNS lookup.
ip - String - The IP address to be investigated.
message - String - The result of the DNS lookup when it is complete.
status - String - The current state of the task.
Response Sample
{ "id": 42, "ip": "String", "message": "String", "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }
GET /services/dns_lookups/{dns_lookup_id}
Retrieves the DNS Lookup status. The result is included if the lookup completes.
Table 10: GET /services/dns_lookups/{dns_lookup_id} Resource Details
MIME Type |
|---|
application/json |
Table 11: GET /services/dns_lookups/{dns_lookup_id} Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
dns_lookup_id | path | Required | Number (Integer) | text/plain | Required - The ID of the DNS lookup to be retrieved. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 12: GET /services/dns_lookups/{dns_lookup_id} Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
200 | The DNS lookup status was retrieved. | |
404 | 1002 | The DNS lookup status does not exist. |
500 | 1020 | An error occurred during the attempt to retrieve the DNS lookup status. |
Response Description
A DNS Lookup object, and the location header set to the task status URL "/services/dns_lookups/{dns_lookup_id}". A DNS status object contains the following fields:
id - Long - The ID of the DNS lookup.
ip - String - The IP address to be investigated.
message - String - The result of the DNS lookup when it is complete.
status - String - The current state of the task.
Response Sample
{ "id": 42, "ip": "String", "message": "String", "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }
GET /services/geolocations
Retrieves the MaxMind geoip data for the given IP address.
Retrieves the MaxMind geoip location data for the given IP address. A filter is required to identify which IP address to lookup. Only EQUALS or IN is supported. Samples:
ip_address = "127.0.0.1"
ip_address IN ( "127.0.0.1", "127.0.0.2" )
Table 13: GET /services/geolocations Resource Details
MIME Type |
|---|
application/json |
Table 14: GET /services/geolocations Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
filter | query | Optional | String | text/plain | Optional - This parameter is used to restrict the elements in a list base on the contents of various fields. |
Table 15: GET /services/geolocations Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
200 | The location data was retrieved. | |
404 | 1002 | The IP address does not exist in the database. |
422 | 1005 | The provided IP address is invalid. |
422 | 1010 | A request parameter is not valid. |
500 | 1020 | An error occurred while looking up the geodata. |
Response Description
The location data after it has been retrieved. A location object contains the following fields:
ip_address - String - The IP address to lookup.
city - City - Object containing details about the city that is associated with the IP address.
name - String - The name of the city.
geo_id - Integer - A unique identifier for the city as specified by GeoNames.
confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the city is correct.
continent - Continent - Object containing details about the continent that is associated with the IP address.
name - String - The name of the continent.
geo_id - Integer - A unique identifier for the continent as specified by GeoNames.
code - String - A two-character code for the continent associated with the IP address.
physical_country - Country - Object containing details about the country where MaxMind believes the end user is located.
name - String - The name of the country.
geo_id - Integer - A unique identifier for the country as specified by GeoNames.
iso_code - String - A two-character ISO 3166-1 country code for the country associated with the IP address.
confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the country is correct.
registered_country - Country - Object containing details about the country in which the ISP has registered the IP address.
name - String - The name of the country.
geo_id - Integer - A unique identifier for the country as specified by GeoNames.
iso_code - String - A two-character ISO 3166-1 country code for the country associated with the IP address.
confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the country is correct.
represented_country - Country - Object containing details about the country which is represented by users of the IP address. For instance, the country represented by an overseas military base.
name - String - The name of the country.
geo_id - Integer - A unique identifier for the country as specified by GeoNames.
iso_code - String - A two-character ISO 3166-1 country code for the country associated with the IP address.
confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the country is correct.
type - String - The type of represented country. Currently limited to military but may include other types in the future.
location - Location - Object containing details about the city that is associated with the IP address.
accuracy_radius - Integer - The approximate accuracy radius in kilometers around the latitude and longitude for the IP address. This is the radius where MaxMind has a 67% confidence that the device using the IP address resides within the circle centered at the latitude and longitude with the provided radius.
average_income - Integer - The average income associated with the IP address.
latitude - Double - The approximate latitude of the location associated with the IP address. Latitude and Longitude are often near the center of population.
longitude - Double - The approximate longitude of the location associated with the IP address. Latitude and Longitude are often near the center of population.
metro_code - Integer - The metro code associated with the IP address. These are only available for IP addresses in the US. Returns the same metro codes as the Google AdWords API.
population_density - Integer - The estimated number of people per square kilometer.
time_zone - String - The time zone associated with location, as specified by the IANA Time Zone Database. For example, “America/New_York”.
postal - Postal - Object containing details about the postal code that is associated with the IP address.
postal_code - String - The postal code associated with the IP address. These are available for some IP addresses in Australia, Canada, France, Germany, Italy, Spain, Switzerland, United Kingdom, and the US. Returns the first 3 characters for Canadian postal codes. Returns the the first 2-4 characters (outward code) for postal codes in the United Kingdom.
confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the postal code is correct.
subdivision - List of Subdivisions - Each of these objects contains details about a subdivision of the country in which the IP address resides. Subdivisions are arranged from largest to smallest.
name - String - The name of the subdivision.
geo_id - Integer - A unique identifier for the region as specified by GeoNames.
iso_code - String - A string of up to three characters that contains the region-portion of theISO 3166-2 code for the region associated with the IP address.
confidence - Integer - A value from 0-100 that represents MaxMind's confidence that the region is correct.
traits - Traits - Object containing general traits that is associated with the IP address.
autonomous_system_number - Integer - The autonomous system number associated with the IP address.
autonomous_system_organization - String - The organization associated with the registered autonomous system number for the IP address.
domain - String - The second level domain associated with the IP address.
internet_service_provider - String - The name of the Internet Service Provider associated with the IP address.
organization - String - The name of the organization associated with the IP address.
user_type - String - The user type associated with the IP address.
geo_json - GeoJSON - A standardize GeoJSON point object for the IP address.
type - String - The type of GeoJSON. The default is "Point".
coordinates - Array of Double - Latitude and Longitude from the Maxmind Location object.
is_local - Boolean - True if the IP address is defined in the network hierarchy.
network - String - The local network that the IP address belongs to.
domain_id - Integer - The domain id of the local network.
Response Sample
[ { "city": { "confidence": 42, "geo_id": 42, "name": "String" }, "continent": { "code": "String", "geo_id": 42, "name": "String" }, "domain_id": 42, "geo_json": { "coordinates": [ 42.5 ], "type": "String" }, "ip_address": "String", "is_local": true, "location": { "accuracy_radius": 42, "average_income": 42, "latitude": 42.5, "longitude": 42.5, "metro_code": 42, "population_density": 42, "timezone": "String" }, "network": "String", "physical_country": { "confidence": 42, "geo_id": 42, "iso_code": "String", "name": "String" }, "postal": { "confidence": 42, "postal_code": "String" }, "registered_country": { "confidence": 42, "geo_id": 42, "iso_code": "String", "name": "String" }, "represented_country": { "confidence": 42, "geo_id": 42, "iso_code": "String", "name": "String" }, "subdivisions": [ { "confidence": 42, "geo_id": 42, "iso_code": "String", "name": "String" } ], "traits": { "autonomous_system_number": 42, "autonomous_system_organization": "String", "domain": "String", "internet_service_provider": "String", "organization": "String", "user_type": "String" } } ]
POST /services/port_scans
Creates a new PortScans lookup. Port scan completes in the background. This endpoint is not available on SaaS systems. It return a 404 error.
Table 16: POST /services/port_scans Resource Details
MIME Type |
|---|
application/json |
Table 17: POST /services/port_scans Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
IP | query | Required | String | text/plain | Used to retrieve the port scan lookup. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 18: POST /services/port_scans Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
201 | he PortScans lookup was created successfully. | |
500 | 1020 | An internal server error occurred during the creation of the port scan lookup. |
Response Description
A port scan object and the location header set to the task status URL "/services/port_scans/{port_scan_id}". A port scan status object contains the following fields:
id - Long - The ID of the port scan.
ip - String - The IP address to be investigated.
message - String - The result of the port scan when it is complete.
status - String - The current state of the task.
Response Sample
{ "id": 42, "ip": "String", "message": "String", "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }
GET /services/port_scans/{port_scan_id}
Retrieves the port scan status. The result is included if the port scan completes.
Table 19: GET /services/port_scans/{port_scan_id} Resource Details
MIME Type |
|---|
application/json |
Table 20: GET /services/port_scans/{port_scan_id} Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
port_scan_id | path | Required | Number (Integer) | text/plain | Required - The ID of the port scan to be retrieved. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 21: GET /services/port_scans/{port_scan_id} Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
200 | The port scan status was retrieved. | |
404 | 1002 | The port scan sStatus does not exist. |
500 | 1020 | An error occurred during the attempt to retrieve the port scan status. |
Response Description
A port scan object and the location header set to the task status url "/services/port_scans/{port_scan_id}". A port scan status object contains the following fields:
id - Long - The ID of the port scan.
message - String - The result of the port scan when complete.
status - String - The current state of the task.
Response Sample
{ "id": 42, "ip": "String", "message": "String", "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }
POST /services/whois_lookups
Creates a new WHOIS lookup. Lookup completes in the background.
Table 22: POST /services/whois_lookups Resource Details
MIME Type |
|---|
application/json |
Table 23: POST /services/whois_lookups Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
IP | query | Required | String | text/plain | Used to retrieve the WHOIS lookup. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 24: POST /services/whois_lookups Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
201 | The WHOIS lookup was created successfully. | |
500 | 1020 | An internal server error occurred during the creation of the WHOIS lookup. |
Response Description
A WHOIS lookup object, and the location header that is set to the task status URL "/services/whois_lookups/{whois_lookup_id}". A WHOIS status object contains the following fields:
id - Long - The ID of the WHOIS lookup.
ip - String - The IP address to be investigated.
message - String - The result of the WHOIS lookup when complete.
status - String - The current state of the task.
Response Sample
{ "id": 42, "ip": "String", "message": "String", "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }
GET /services/whois_lookups/{whois_lookup_id}
Retrieves the WHOIS lookup status. The result is included if the lookup completes.
Table 25: GET /services/whois_lookups/{whois_lookup_id} Resource Details
MIME Type |
|---|
application/json |
Table 26: GET /services/whois_lookups/{whois_lookup_id} Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
|---|---|---|---|---|---|
whois_lookup_id | path | Required | Number (Integer) | text/plain | Required - The ID of the WHOIS lookup to be retrieved. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 27: GET /services/whois_lookups/{whois_lookup_id} Response Codes
HTTP Response Code | Unique Code | Description |
|---|---|---|
200 | The WHOIS lookup status was retrieved. | |
404 | 1002 | The WHOIS lookup status does not exist. |
500 | 1020 | An error occurred during the attempt to retrieve the WHOIS lookup status. |
Response Description
A WHOIS lookup object, and the location header that is set to the task status URL "/services/whois_lookups/{whois_lookup_id}". A WHOIS status object contains the following fields:
id - Long - The ID of the WHOIS lookup.
ip - String - The IP address to be investigated.
message - String - The result of the WHOIS lookup when it is complete.
status - String - The current state of the task.
Response Sample
{ "id": 42, "ip": "String", "message": "String", "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }