Get Started

Create an account and api-key

  1. Create an account

  2. Authenticate your account

  3. Get packages available to your account
    (Every account starts with a package that has limited geography access. You can search the entire United States and download more records at a time after reaching a pricing agreement for your application)

  4. Create an API key

  5. Authenticate your API key

Getting the following information will help construct your request for counts/data

  1. Get datasets

  2. Get search-fields

  3. Get search-values

  4. Construct a criteria JSON object

  5. Get counts

  6. Get return-fields

  7. Get data

API Endpoints

Try out the endpoints using admin-token or token generated using authentication method for real time requests and responses

https://papi.infofree.com/v1/{resource-path}

accounts

The account is the billable profile. Users of your application can be directed to a portal to complete transactions such as upgrading their api packages and adding credits. These packages will be set up when when we reach a pricing agreement for your application.

api-keys

Multiple api-keys can be created in an account. Once an api-key is authenticated, use its token to get data.

api-packages

An api-package defines access to datasets, search-fields and search-values, as well as the rate at which an api-key may make requests. Each api-key is created with and has an api-package. An api-key's package can be changed using the portal. The packages available for selection are settled in a pricing agreement for your application.

datasets

The sets of data an API key can search on. There are over 100 available. Ex: businesses, consumers

search-fields

The fields an API key can search with on a given dataset. Ex: {"field":"state","value":"AK"}

search-values

The values an API key can search for on a given search-field. Ex: {"field":"state","value":"AK"}

tokens

An admin-token is given after account authentication. A token is given after api-key authentication.

criteria

Criteria are specified in JSON format. The format uses a tree structure, and thus has nodes and leafs.

The request criteria in the box below equates to the following sql query:
(( Physical_Zip = '68136' OR Physical_State = 'AK' ) AND( Employees_Location_Code = 'A' AND( Sales_Model_Code = 'A' OR Sales_Model_Code = 'B' ) ) )

[  
   [  
      {  
         "type":"node",
         "log-op":"and"
      },
      {  
         "field":"zip-code",
         "value":"68136",
         "log-op":"or"
      },
      {  
         "field":"state",
         "value":"AK",
         "log-op":"or"
      }
   ],
   [  
      {  
         "type":"node",
         "log-op":"and"
      },
      {  
         "field":"employees-size-code",
         "value":"A",
         "log-op":"or"
      },
      [  
         {  
            "type":"node",
            "log-op":"and"
         },
         {  
            "field":"annual-sales-volume-code",
            "value":"A",
            "log-op":"or"
         },
         {  
            "field":"annual-sales-volume-code",
            "value":"B",
            "log-op":"or"
         }
      ]
   ]
]

Nodes

Nodes are represented with JSONArrays. They are allowed as a way to incorporate what would be equivalent to parenthesis and allow nesting.
Nodes can have a JSONObject with type 'node' and 'log-op' to specify how the node will logically be joined with preceding criteria parts. If multiple such objects are defined in one JSONArray, the last one will be used. If no such object exists, the log-op 'or' will be used.

Required attributes:
  • "type" : "node"

Leafs

Leafs are represented with JSONObjects. Every leaf must have at least a field and value. 'log-op' is used as the logical operator to join leafs, the default is 'or'. 'rel-op' is the relational operator to join field and value, if it is not specified, it will default to '='.

Optional attributes:
  • rel-op - default: '='
  • log-op - default: "or"
  • type - default: "leaf"

Required attributes:
  • field
  • value

Logical Operators

The following operators are allowed for the log-op attribute:

  • and
  • or

Relational Operators

The default relational operator for a criteria is '='. You will find the valid rel-op for the field you are searching on by calling /search-fields.

Special Cases

Fields may have special handlers, since they cannot be represented by a simple key value pair. These are the functions currently supported.

Geography searches:
  • func-radius
  • func-polygon
  • func-bounding-box
  • func-area-code-within-state

Geography search by radius (> 0 and <= 50 miles):
{
  "field": "func-radius",
  "value": {
    "latitude": "33.4634472",
    "longitude": "-84.4501006",
    "radius": "15"
  }
}
Geography search by many-sided shape: (if last point is not equals to first, the shape will be automatically closed):
{
  "field": "func-polygon",
  "value": [
    {
      "latitude": 43.453915811889,
      "longitude": -111.40274047852
    },
    {
      "latitude": 40.045488893504,
      "longitude": -109.90859985352
    },
    {
      "latitude": 41.113503446378,
      "longitude": -105.07461547852
    },
    {
      "latitude": 43.89888194443,
      "longitude": -105.77774047852
    }
  ]
}
Geography search by bounding box:
{
   "field":"func-bounding-box",
   "value":{
      "northeast-longitude":"-96.06170788407326",
      "southwest-longitude":"-96.08144894242287",
      "southwest-latitude":"41.190540550958886",
      "northeast-latitude":"41.2052653286742"
   }
}
Geography search by area code within a state:
{
   "field":"func-area-code-within-state",
   "value":{
      "area-code":"402",
      "state":"NE"
   }
}