Overview

Use the Submission API to Suggest improvements to the Data Axle Database. As Data Axle’s data specialists research each suggestion, final results are returned in real-time.

Correcting an Attribute

POST /v1/places/submissions

The basic way to provide feedback is by submitting a correction to an existing place. Doing so requires knowing the infogroup_id of the business, along with the field and value to correct.

For example, to submit a new phone for a business with an infogroup_id of "987765321":

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "phone": "(334) 284-9600"
  }
}'

The response returns the result, ID of the submission, and echos the submission request:

{
  "result": "success",
  "id": "5f0b1070c3e4761cabf116bbed2b49c40781a441",
  "infogroup_id": "987765321",
  "attributes": {
    "phone": "(334) 284-9600"
  },
  "meta": {},
  "comments": {},
  "verify": null
}

Data Axle reviews new values before applying the changes to the database. Use the results endpoint to retrieve the outcome of submissions.

Working with Multiple Attributes

More than one attribute can be sent within each submission:

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "phone": "(334) 284-9600",
    "name": "Best Pizza in the World"
  }
}'

The definition of all attributes and their formats can be found in supplemental documentation.

Errors

If the input is invalid, the response returns the validation errors. This request produces a validation error:

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "phone": "bad-number"
  }
}'

A bad request with errors produces a JSON response with an errors key:

{
  "result": "failure",
  "errors": {
    "phone": ["is invalid"]
  }
  ...
}

Nested Attributes

Certain fields contain a collection of objects, which then contain attributes. Updating these fields is a bit more complex than suggesting the new value.

replace, remove, modify and create are the valid keys. If replace is provided, the other options cannot be sent.

Nested Replacement

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "tags": {
      "replace": [
        { "sic_code_id": "123456", "primary": true },
        { "sic_code_id": "987654", "primary": false }
      ]
    }
  }
}'

This clears all tags on the place and replaces them with the given set. The client is required to know every tag on the place and does not allow just adding a value.

Send an empty value for replace to clear the list.

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "operating_hours": {
      "replace": []
    }
  }
}'

Sending an empty hash for the field is supported and will result in no changes.

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "operating_hours": {}
  }
}'

Nested Granular Changes

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "tags": {
      "remove": [{"id": "fd69fbdddc8c4dd998708475d7f35c4a"}],
      "modify": [
        { "id": "4289ac2101c24b018c20feecea092949", "sic_code_id": "011198", "primary": false }
      ],
      "create": [
        { "sic_code_id": "757383", "primary": true }
      ]
    }
  }
}'

This allows adding or changing individual tags without knowing about all the other tags. The client must know the tag IDs to remove or change them.

Internally, Data Axle will try to match create with existing objects. For tags, matching is performed by finding an existing tag by the SIC Code. For Contacts, it looks for existing records based on the name and email of the contact. Matched records will be updated with the attributes submitted in the create directive.

Array attributes

Certain fields contain a collection of values. Updating these fields is a bit more complex than suggesting the new value.

replace, remove, create are the valid keys. If replace is provided, the other options cannot be sent.

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "payment_types": {
      "remove": ["Google Checkout"],
      "create": ["Cash", "Visa", "Mastercard"]
    }
  }
}'

Send an empty value for replace to clear the list.

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "payment_types": {
      "replace": []
    }
  }
}'

Sending an empty hash for the field is supported and will result in no changes.

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "payment_types": {}
  }
}'

Commenting on an Attribute

If the current value is suspect of being wrong, but no new value can be provided, the field can be commented on:

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "comments": {
    "phone": "The number seems to be disconnected"
  }
}'

Suggesting a new place

Suggesting a new business requires a core set of attributes: name, street, city, state, zip. A phone or website helps verify the business.

This sample request shows minimal information to suggest a new place:

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "attributes": {
    "name": "Pizza by Bob",
    "street": "470 Taylor Road",
    "city": "Montgomery",
    "state": "AL",
    "zip": "36117",
    "phone": "(334) 284-9600"
  }
}'

infogroup_id will be null in the response.

{
  "result": "success",
  "id": "1217186bb4f854511abb1a0869c1d2116b18a26c",
  "infogroup_id": null
  ...
}

The new business is reviewed by Data Axle to determine if it is correct.

Bulk Requests

POST /v1/places/submissions/bulk

The bulk endpoint supports sending many submissions in one request. A request contains a submissions key containing an array of submissions. The following example shows how a new name is suggested for infogroup_id "987765321", and comments on the phone for infogroup_id "430398671".

curl https://qa.api.data-axle.com/v1/places/submissions/bulk -d '
{
  "submissions": [
    {
      "infogroup_id": "987765321",
      "attributes": {
        "name": "Texan BBQ House"
      }
    },
    {
      "infogroup_id": "430398671",
      "comments": {
        "phone": "The number seems to be disconnected"
      }
    }
  ]
}'

The above request responds with the result of each submission. Each result is returned in the same order as provided in the request:

{
  "submissions": [
    {
      "result": "success",
      "id": "5cbb3b15c8bee0f706239b45cb763fed"
    },
    {
      "result": "success",
      "id": "2e849855d32e1e20eb33e3b74a7785b2"
    }
  ]
}

Additional Submission fields

In addition to suggesting corrections and commenting on attributes for Data Axle to review, each submission supports the following options:

determined_at is used to describe when the information was acquired. For example, if an external system acquired the information on December 24th and did not submit the information until December 25th, then this field would be used. The Submission API defaults determined_at to the current time.

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "phone": "(334) 284-9600"
  },
  "determined_at": "2014-12-24T01:29:08Z"
}'

verify is used to denote which fields in the submission were verified. Nested attributes can be verified by specifying their IDs.

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "name": "Pizza a la Mario",
    "phone": "(334) 284-9600",
    "fax_number": "(206) 555-9540"
  },
  "verify": {
    "name": null,
    "phone": null,
    "tags": ["1234"]
  }
}'

meta is used to send metadata as key value pairs. This is a flexible way to describe unstructured information about each submission:

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "attributes": {
    "fax_number": "(206) 555-9540"
  },
  "meta": {
    "weather": "cloudy",
    "source": "facebook"
  }
}'

Up to 10 meta keys are accepted per submission.

Retrieving Results

GET /v1/places/submissions/results

Calling the endpoint without any parameters fetches the first set of available submissions:

curl https://qa.api.data-axle.com/v1/places/submissions/results

The response returns a list of submission results with a list rejected fields and current values:

{
  "next_token": "13835315192676945401741312",
  "results": [
    {
      "submission_id": "711e12e0e1577d2d7a65078f0deccd23680b024c",
      "update_type": "update",
      "infogroup_id": "939010853",
      "rejected": {
        "street": [
          {
            "reason": "human_review",
            "message": "is incorrect"
          }
        ]
      },
      "current": {
        "name": "Bob's Burgers",
        "phone": "(206) 902-6006",
        "street": "418 NW Sesame St",
        "state": "WA"
      },
      "timestamp": "2017-06-20T21:42:30Z",
      "comment": "The street value we had was correct"
    }
  ]
}

Fields

By default, all available fields are included in the output. This can be changed with the fields option. You can supply any field included in your contract. Browse the list of all fields at the Data Dictionary.

{
  "fields": ["name", "street", "city", "state", "postal_code"]
}

Scrolling Through Submission Results

Each request returns up to 100 results, ordered chronologically. To read the next set of results, use the next_token from the previous request and append it to the request URL via the since parameter:

curl https://qa.api.data-axle.com/v1/places/submissions/results?since=15735765364811067196218694

Repeat this process until an empty list of results is returned. Store the final next_token, for use in future requests for new results:

{
  "next_token": "15735765364811067196218694",
  "results": []
}

The Submission Result object

For every field submitted in the original submission, the Submission Result provides either an accepted value or a rejected reason.

• submission_id - The ID of the submission.
• update_type - addition if a new place was created or update for an update to an existing place.
• infogroup_id - The Infogroup ID of the created or updated place.
• rejected - The list of fields rejected and reasons they were rejected.
• current - The current record.
• timestamp - The time and date the result was recorded.
• comment - An optional comment from the associate who reviewed the submission.

Rejections

The list of rejected fields is in the format of field: [{reason: "reason", message: "rejection reason message"}]:

{
  "rejected": {
    "street": [
      {
        "reason": "human_review",
        "message": "is incorrect"
      }
    ]
  }
}

A field rejection does not mean your entire submission is rejected, only the specified fields. When interpreting rejections, only the "reason" should be interpreted programmatically, as the message is subject to change.

Nested Rejections

Rejections of nested attributes will include the associated object "id" if the rejection applies to a specific nested object:

{
  "rejected": {
    "contacts": [
      {
        "reason": "human_review",
        "message": "is incorrect",
        "id": "07a61eebc1c543e6bf94861f4fe46315"
      },
      {
        "reason": "outdated",
        "message": "outdated",
        "id": "2775b40bd2094f18851236922cf53103"
      }
    ]
  }
}

Rejected Submissions

Submissions may be entirely rejected. If rejected, a reason and message will be provided on the "infogroup_id" field:

{
  "accepted": {},
  "rejected": {
    "infogroup_id": [
      {
        "reason": "fictitious_place",
        "message": "not a real place"
      }
    ]
  }
}

Rejection Reasons

Handling duplicates

If the submitted infogroup_id is for a place marked as a duplicate, we automatically redirect the submission to the correct place. The Submission Result API returns the infogroup_id of the correct place.