Manage your plan usage

How Plan Matches are used

When you sign up for an API access plan, you get a certain number of matches each month. One match is one result returned by an API call. The API header shows you how many results are returned with num_results.

Here are some guidelines around when you are using your matches:

No results means no matches used -- If you call the API and it returns no results, it does not count against your monthly match limit.
Repeated calls count as additional matches -- If you repeat a call, it counts as another result, since matches are results returned, not unique results. If you repeat an API call, and get the same results, each returned result counts against your monthly match limit.
If you have no more matches, calls will fail -- If you reach your monthly usage limit, you won't be able to make API calls until your limit resets at the beginning of the next month. Or, you can Upgrade your plan for more matches
Results returned in the Try the API count as matches -- Results returned through Try the API and other live results examples count as matches for your monthly limit.

Example

For example, this API response from the consumer API is returning 2 results blocks (each starts with match_score), so counts as 2 matches:

{
  "versium": {
    "version": "1.0",
    "num_results": 2,
    "query_id": "2bcf3d42123b5f510b8380bb8ddb9d0d",
    "query_time": "0.583",
    "results": [
      {
        "match_score": 100,
        "time_stamp": "20180701",
        "first": "VERONICA",
        "middle": "E",
        "last": "QUEK",
        "address": "915 Main Rd",
        "city": "Sultan",
        "state": "WA",
        "zip": "98294",
        "country": "US",
        "phone": "3605551212",
        "line_type": "Landline"
      },
      {
        "match_score": 100,
        "time_stamp": "20100101",
        "first": "VERONICA",
        "last": "QUEK",
        "address": "204 21ST PL W",
        "city": "LYNNWOOD",
        "state": "WA",
        "zip": "98036",
        "country": "US"
      }
    ],

Control how many results are returned

Use max_recs to limit results -- To control how many matches you use when you call an API, use the max_recs option. For more information, see Common API Inputs and Options.
Fine-tune your matches -- You can fine-tune how the APIs match your inputs using Advanced Matching. Each API is calibrated for the best overall results; however, there may be times when you want to control whether you get only exact matches, or get more matches with fuzzy matching.

How Plan Matches are used

Example

Control how many results are returned

What's Next