Overview

Welcome to the IP Flow API. Here you will find all the documentation required to authenticate and access our data using our self-descriptive endpoints.

The IP Flow API is based on REST. All endpoint requests should be made using SSL over HTTPS. All response bodies are encoded in JSON.

Was this section helpful?

Versioning

The IP Flow API is version based. Any future changes to our API that are not backwards compatible will be reflected in new versions.

Each version is identified as part of the endpoint URL. Version 1.0 of the search endpoint is identified by /v1.0/search.

Versions
Version URL Status
Version 1.0 /v1.0/ Current
Was this section helpful?

Errors

The IP Flow API using HTTP response codes to indicate success or failure. A general status for each range is listed below.

Code Range General Meaning Example
2xx Success 200 - Success
4xx Failure (Request based) 429 - API limit reached
5xx IP Flow API Error 500 - internal server error

Each endpoint has specific response codes. Exact response codes and their meanings are listed under each endpoint in this documentation.

Was this section helpful?

Authentication

The IP Flow API uses a JWT Token to authenticate requests.

You can obtain your JWT Token by contacting your Customer Success Manager.

The JWT Token is a sequence of letters, numbers and symbols and looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6Im1pZ3VlbCIsIm5iZiI6MTU5NTUxNzY5NywiZXhwIjoxNjI3MDUzNjk3LCJpYXQiOjE1OTU1MTc2OTcsInRlc3QxIjoidGVzdCIsInRlc3QyIjoidGVzdGRhIiwiQWNjZXNzTGV2ZWwiOiJUaWVyMSIsIkNsaWVudCI6IntcIkNsaWVudElkXCI6MzAwMCxcIlRva2VuSWRcIjoxLFwiTmFtZVwiOlwibWlndWVsXCIsXCJUdGxcIjpcIjM2NS4wMDowMDowMFwiLFwiQWNjZXNzTGV2ZWxcIjoxLFwiTWF4TWludXRlXCI6MjAwMCxcIk1heERheVwiOjEwMDAwMCxcIk1heE1vbnRoXCI6MTAwMDAwLFwiQ2xpZW50S2V5XCI6XCIzMDAwXzFcIixcIk1heE1pbnV0ZUtleVwiOlwiMzAwMF8xX01heE1pbnV0ZVwiLFwiTWF4RGF5S2V5XCI6XCIzMDAwXzFfTWF4RGF5XCIsXCJNYXhNb250aEtleVwiOlwiMzAwMF8xX01heE1vbnRoXCJ9In0.9USRCcTz7uxy5EGOh4PlFYnvSvzMINWA1XNqiByPsHA

Each request will require your JWT Token to be present in the HTTP Authorization header as a Bearer token like in the example below:

Bearer <<YOUR-JWT-TOKEN>>

Your JWT Token will give you access to specific endpoints and limits according to your access level.

Was this section helpful?

Single IP Address

This endpoint allows you to request the business information for a single IP address. The response returns a Business entity.

Endpoint
URL https://api.ipflow.com/v1.0/search/ipaddress/[ipaddress]
Method GET
Parameters
ipAddress The IP Address for the query
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a Business entity with the structure like exemplified on the right.

Please check the Business entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
message A message describing the error
key The IP Address passed to the endpoint
HTTP Status Code Description
204 No Content The IP Address was found in our database but does not have a Business associated to it.
400 Bad Request The IP Address was empty or invalid.
401 Unauthorized The user was not authorized to access this endpoint.
404 Not Found The IP Address was not found in our database.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/search/ipaddress/[ipaddress] \ 
     --request GET \ 
     --header 'Authorization: Bearer YOUR-TOKEN' \
Response
{
  "businessId": "00000001",
  "officeId": "00000001",
  "businessName": "IP Flow",
  "location": {
    "addressLine1": "3000 Lakeside",
    "addressLine2": "North Harbour",
    "addressLine3": null,
    "addressLine4": null,
    "town": "Portsmouth",
    "regionId": 719,
    "region": "Hampshire",
    "regionTypeId": 2,
    "regionType": "County",
    "postalCode": "PO6 3EN",
    "countryCode": "GB",
    "country": "United Kingdom"
  },
  "website": "www.ipflow.com",
  "alternateDomains": null,
  "telephone": "02072 067293",
  "registration": {
    "authority": "Companies House",
    "number": "07158006",
    "year": "2010",
    "dateOfCreation": "2010-02-15"
  },
  "industries": [
    {
      "groupName": "Computing",
      "level": 1,
      "id": 26,
      "name": "Computer Software",
      "groupId": 27
    }
  ],
  "industryClassifications": [
    {
      "type": "SIC",
      "code": "62090",
      "description": "Other information technology service activities",
      "sectionCode": "J",
      "sectionDescription": "Information and communication",
      "divisionCode": "62",
      "divisionDescription": "Computer programming, consultancy and related activities",
      "groupCode": "62.0",
      "groupDescription": "Computer programming, consultancy and related activities"
    }
  ],
  "employeeBandId": 5,
  "employeeBand": "200-499",
  "turnover": {
    "amount": 12345.6789,
    "type": 2,
    "band": 2,
    "bandDescription": "£10000 to £24,999",
    "currencySymbol": "£",
    "currencyName": "Pound sterling",
    "isoCurrencySymbol": "GBP"
  },
  "accountsNextDue": "2020-12-31",
  "previousBusinessNames": [
    "Web Forensics Limited"
  ],
  "businessLinks": null,
  "statusCode": 200,
  "message": null,
  "key": "[ipaddress]"
}

Search IP Address Usage

This endpoint allows you to request the usage information for the current month related to the single IP address endpoint. The response returns a Search IP Address Usage entity.

Endpoint
URL https://api.ipflow.com/v1.0/search/ipaddress/usage
Method GET
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a Search IP Address Usage entity.

Please check the Search IP Address Usage entity page for more details.

Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/search/ipaddress/usage \ 
     --request GET \ 
     --header 'Authorization: Bearer YOUR-TOKEN' \
Response
{
  "currentDayCount": 10,
  "currentDayRemainder": 90,
  "currentMonthCount": 100,
  "currentMonthRemainder": 900
}

Countries

This endpoint returns a static list of Country entities.

Endpoint
URL https://api.ipflow.com/v1.0/staticdata/countries
Method GET
Parameters
None  
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a list of Country entities with the structure like exemplified on the right.

Please check the Country entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
HTTP Status Code Description
401 Unauthorized The user was not authorized to access this endpoint.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/staticdata/countries \ 
     --request GET \ 
     --header 'Authorization: Bearer YOUR-TOKEN' \
Response
[
  {
    "countryCode": "GB",
    "name": "United Kingdom"
  },
  {
    "countryCode": "US",
    "name": "United States"
  },
  {
    "countryCode": "...",
    "name": "..."
  }
]

Employee Bands

This endpoint returns a static list of Employee Band entities.

Endpoint
URL https://api.ipflow.com/v1.0/staticdata/employeebands
Method GET
Parameters
None  
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a list of Employee Band entities with the structure like exemplified on the right.

Please check the Employee Band entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
HTTP Status Code Description
401 Unauthorized The user was not authorized to access this endpoint.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/staticdata/employeebands \ 
     --request GET \ 
     --header 'Authorization: Bearer YOUR-TOKEN' \
Response
[
  {
    "id": 1,
    "name": "1-20"
  },
  {
    "id": 2,
    "name": "21-49"
  },
  {
    "id": 3,
    "name": "..."
  }
]

Industries

This endpoint returns a static list of Industry entities.

Endpoint
URL https://api.ipflow.com/v1.0/staticdata/industries
Method GET
Parameters
None  
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a list of Industry entities with the structure like exemplified on the right.

Please check the Industry entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
HTTP Status Code Description
401 Unauthorized The user was not authorized to access this endpoint.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/staticdata/industries \ 
     --request GET \ 
     --header 'Authorization: Bearer YOUR-TOKEN' \
Response
[
  {
    "id": 26,
    "name": "Computer Software",
    "groupId": 27
  },
  {
    "id": 71,
    "name": "Investment Banking",
    "groupId": 45
  },
  {
    "id": 120,
    "name": "Staffing and Recruitment",
    "groupId": 15
  },
  {
    "id": 3,
    "name": "...",
    "groupId": 0
  }
]

Industry Groups

This endpoint returns a static list of Industry Group entities.

Endpoint
URL https://api.ipflow.com/v1.0/staticdata/industrygroups
Method GET
Parameters
None  
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a list of Industry Group entities with the structure like exemplified on the right.

Please check the Industry Group entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
HTTP Status Code Description
401 Unauthorized The user was not authorized to access this endpoint.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/staticdata/industrygroups \ 
     --request GET \ 
     --header 'Authorization: Bearer YOUR-TOKEN' \
Response
[
  {
    "id": 15,
    "name": "Business Services"
  },
  {
    "id": 27,
    "name": "Computing"
  },
  {
    "id": 45,
    "name": "Financial Services"
  },
  {
    "id": 3,
    "name": "..."
  }
]

Regions

This endpoint returns a static list of Region entities.

Endpoint
URL https://api.ipflow.com/v1.0/staticdata/regions
Method GET
Parameters
None  
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a list of Region entities with the structure like exemplified on the right.

Please check the Region entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
HTTP Status Code Description
401 Unauthorized The user was not authorized to access this endpoint.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/staticdata/regions \ 
     --request  \ 
Response
[
  {
    "id": 706,
    "name": "Dorset",
    "regionTypeId": 2,
    "countryCode": "GB"
  },
  {
    "id": 719,
    "name": "Hampshire",
    "regionTypeId": 2,
    "countryCode": "GB"
  },
  {
    "id": 762,
    "name": "Somerset",
    "regionTypeId": 2,
    "countryCode": "GB"
  },
  {
    "id": 670,
    "name": "...",
    "regionTypeId": 2,
    "countryCode": "..."
  }
]

Region Types

This endpoint returns a static list of Region Type entities.

Endpoint
URL https://api.ipflow.com/v1.0/staticdata/regiontypes
Method GET
Parameters
None  
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a list of Region Type entities with the structure like exemplified on the right.

Please check the Region Type entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
HTTP Status Code Description
401 Unauthorized The user was not authorized to access this endpoint.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/staticdata/regiontypes \ 
     --request  \ 
Response
[
  {
    "id": 1,
    "name": "State"
  },
  {
    "id": 2,
    "name": "County"
  },
  {
    "id": 3,
    "name": "..."
  }
]

SIC Codes

This endpoint returns a static list of SIC Code entities.

Endpoint
URL https://api.ipflow.com/v1.0/staticdata/siccodes
Method GET
Parameters
None  
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a list of Sic Code entities with the structure like exemplified on the right.

Please check the SIC Code entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
HTTP Status Code Description
401 Unauthorized The user was not authorized to access this endpoint.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/staticdata/siccodes \ 
     --request  \ 
Response
[
  {
    "code": "62012",
    "description": "Business and domestic software development",
    "sectionCode": "J",
    "sectionDescription": "Information and communication",
    "divisionCode": "62",
    "divisionDescription": "Computer programming, consultancy and related activities",
    "groupCode": "62.0",
    "groupDescription": "Computer programming, consultancy and related activities"
  },
  {
    "code": "64191",
    "description": "Banks",
    "sectionCode": "K",
    "sectionDescription": "Financial and insurance activities",
    "divisionCode": "64",
    "divisionDescription": "Financial service activities, except insurance and pension funding",
    "groupCode": "64.1",
    "groupDescription": "Monetary intermediation"
  },
  {
    "code": "78300",
    "description": "Human resources provision and management of human resources functions",
    "sectionCode": "N",
    "sectionDescription": "Administrative and support service activities",
    "divisionCode": "78",
    "divisionDescription": "Employment activities",
    "groupCode": "78.3",
    "groupDescription": "Other human resources provision"
  },
  {
    "code": "...",
    "description": "...",
    "sectionCode": "...",
    "sectionDescription": "...",
    "divisionCode": "...",
    "divisionDescription": "...",
    "groupCode": "...",
    "groupDescription": "..."
  }
]

NAICS Codes

This endpoint returns a static list of NAICS Code entities.

Endpoint
URL https://api.ipflow.com/v1.0/staticdata/naicscodes
Method GET
Parameters
None  
Returns

If successful, this endpoint will respond with HTTP Status Code 200 (OK) and a list of NAICS Code entities with the structure like exemplified on the right.

Please check the NAICS Code entity page for more details.

Errors

This endpoint will return one of the HTTP Status Code(s) from the table below and also provide a JSON object with the following properties:

statusCode The HTTP Status Code
HTTP Status Code Description
401 Unauthorized The user was not authorized to access this endpoint.
429 Too Many Requests You have reached one of your limits.
500 Internal Server Error Unknown error
Was this section helpful?
Request
curl https://api.ipflow.com/v1.0/staticdata/naicscodes \ 
     --request  \ 
Response
[
  {
    "code": "541611",
    "description": "Administrative Management and General Management Consulting Services",
    "sectionCode": null,
    "sectionDescription": null,
    "divisionCode": null,
    "divisionDescription": null,
    "groupCode": null,
    "groupDescription": null
  },
  {
    "code": "425110",
    "description": "Business to Business Electronic Markets",
    "sectionCode": null,
    "sectionDescription": null,
    "divisionCode": null,
    "divisionDescription": null,
    "groupCode": null,
    "groupDescription": null
  },
  {
    "code": "921130",
    "description": "Public Finance Activities",
    "sectionCode": null,
    "sectionDescription": null,
    "divisionCode": null,
    "divisionDescription": null,
    "groupCode": null,
    "groupDescription": null
  },
  {
    "code": "...",
    "description": "...",
    "sectionCode": "...",
    "sectionDescription": "...",
    "divisionCode": "...",
    "divisionDescription": "...",
    "groupCode": "...",
    "groupDescription": "..."
  }
]

Entities

Business Entity
Property Name Property Type Property Required
businessId string required
officeId string required
businessName string required
addressLine1 string optional
addressLine2 string optional
addressLine3 string optional
addressLine4 string optional
town string required
regionId int? optional
region string optional
regionTypeId int optional
regionType string optional
postalCode string optional
countryCode string required
country string required
website string optional
alternateDomains string[] optional
telephone string optional
authority string optional
number string optional
year string optional
dateOfCreation date optional
id integer required
name string required
groupId integer required
groupName string required
level integer required
code string required
description string required
sectionCode string required
sectionDescription string required
divisionCode string required
divisionDescription string required
groupCode string required
groupDescription string required
type string required
employeeBandId int? optional
employeeBand string optional
amount decimal required
type int (1 - Modelled; 2 - Real) required
band int required
bandDescription string required
currencyName string required
currencySymbol string required
isoCurrencySymbol string required
accountsNextDue date optional
previousBusinessNames string[] optional
statusCode int required
message string optional
key string required
Search IP Address Usage Entity
Property Name Property Type Property Required
currentDayCount int required
currentDayRemainder int required
currentMonthCount int required
currentMonthRemainder int required
Country Entity
Property Name Property Type Property Required
countryCode string required
name string required
Employee Band Entity
Property Name Property Type Property Required
id integer required
name string required
Industry Entity
Property Name Property Type Property Required
id integer required
name string required
groupId integer required
Industry Group Entity
Property Name Property Type Property Required
id integer required
name string required
Region Entity
Property Name Property Type Property Required
id integer required
name string required
regionTypeId integer required
countryCode string required
Region Type Entity
Property Name Property Type Property Required
id integer required
name string required
SIC Code Entity
Property Name Property Type Property Required
code string required
description string required
sectionCode string required
sectionDescription string required
divisionCode string required
divisionDescription string required
groupCode string required
groupDescription string required
NAICS Code Entity
Property Name Property Type Property Required
code string required
description string required
Was this section helpful?

Brand

The colorways and shape of the logo should not be modified, and there should be a space around the logo of at least 150% the size of the logo.

The color version of the logo should be used on predominantly light backgrounds.

ip flow logo