Getting started

POST /v1/financial_data/match

The Match API v1 uses fuzzy logic with various sets of rules to match and append to your data.

The difference between Search API and Match API is that Search API returns exact results from filters, whereas Match API matches your entities to the Data Axle database.

curl https://qa.api.data-axle.com/v1/financial_data/match \
  -H "X-AUTH-TOKEN: ffddaa789012345678901234" \
  -d '{
    "identifiers": {
      "name": "Acme Corporation",
      "street": "123 Business Blvd",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001"
    }
  }'

The response includes a persistent company_id along with appended attributes:

{
  "document": {
    "company_id": "123456789",
    "rules": [
      "name",
      "address"
    ],
    "score": 0.88,
    "attributes": {
      "company_id": "123456789",
      "infogroup_id": "939010853",
      "name": "Acme Corporation",
      "company_name": "Acme Corporation",
      "company_address": "123 Business Blvd",
      "company_city": "New York",
      "company_state": "NY",
      "company_postal_code": "10001",
      ...
    }
  }
}

• GET or POST can be used.
• By default, one match is returned. Set the limit option to retrieve multiple matches.
• All available fields are included in the output. This can be changed with the fields option.
• If a match is not found, a null document is returned.

Parameters

Identifiers

The fields you can submit for matching are:

See the rule descriptions for which fields are required for each rule to match.

reference_id is not used for matching, but is an optional field that can be used to reference requests using an ID from your own system. It will be returned with the results of batch requests.

Rules

Rules are automatically selected based on the data provided.

Records that only match a single rule will only be returned if the rule is marked as "high confidence". If only one rule was run, such as when only an address is provided, address matches will be included in the result.

Score

Match scores are provided to make it easier to compare the similarity of the input to the matched record. Records are scored 0-1, with a higher score indicating greater similarity.

Different use cases may benefit from different score threshold considerations. We recommend using matches with a score of 0.8 or above and matched using least two rules. Matching using multiple rules will increase match quality.

To exclude low-confidence matches from your results, use the minimum_match_score parameter.

{
  "minimum_match_score": 0.8
}

Required Rule Groups

Use the required_rule_groups parameter to specify groups of rules. Only results that match one or more of the groups are returned.

{
  "required_rule_groups": [
    ["address", "name"],
    ["address", "phone"]
  ]
}

In this example, a record matches in the following cases:

• The record matches the "address" and "name" rule.
• The record matches the "address" and "phone" rule.
• The record matches the "address", "name", and "phone" rule.

Match Rule Groups Exactly

When match_rule_groups_exactly is true, groups of rules specified in required_rule_groups must match exactly in order to be returned.

{
  "required_rule_groups": [
    ["address", "name"],
    ["address", "phone"]
  ],
  "match_rule_groups_exactly": true
}

In this example, a record matches in the following cases:

• The record matches the "address" and "name" rule.
• The record matches the "address" and "phone" rule.

The rule set '["address", "name", "phone"]' will not match.

Filters

The filter parameter reduces results to records matching a specified criteria, using the Filter DSL.

Fields

By default, all fields in the Data Dictionary are included in the output. Use the fields parameter to reduce the number of elements returned:

{
  "fields": ["company_id", "infogroup_id", "name", "company_name", "company_address", "company_city"]
}

Some contact information, including email addresses, will be used for matching, but will not be included with the matched record. Some data may be suppressed for certain records and will not be returned.

Include Labels

The fields returned within records frequently contain encoded values that reference lookup data. To retrieve the labels for lookups, add the include_labels option:

{
  "include_labels": true
}

Read the Lookups API documentation for more information.

Limit

By default, one match is returned. Specify a limit parameter to retrieve multiple matches. When limit is specified, an array of documents is returned.

{
  "identifiers": {
    "name": "Tech Solutions",
    "street": "Main St",
    "city": "San Francisco",
    "state": "CA"
  },
  "limit": 2
}

{
  "documents": [{
      "company_id": "987654321",
      "rules": [
        "name",
        "address"
      ],
      "score": 0.92,
      "attributes": {
        "company_id": "987654321",
        "infogroup_id": "555123456",
        "name": "Tech Solutions Inc",
        "company_name": "Tech Solutions Inc",
        "company_city": "San Francisco",
        "company_state": "CA"
      }
    },
    {
      "company_id": "123789456",
      "rules": [
        "name",
        "address"
      ],
      "score": 0.85,
      "attributes": {
        "company_id": "123789456",
        "infogroup_id": "555654321",
        "name": "Tech Solutions LLC",
        "company_name": "Tech Solutions LLC",
        "company_city": "San Francisco",
        "company_state": "CA"
      }
    }
  ]
}

Packages

Select packages of fields by providing a package param_key to the packages parameter. By default, every field on a package is returned. The packages parameter is combined with the fields parameter to return only specified fields.

{
  "packages": ["base_v1"]
}