Overview

Use the Submission API to suggest improvements to existing places or add new records to the Data Axle database. Data Axle associates review each submission for accuracy before applying changes to the database, allowing partial acceptance of a request.

Results are returned asynchronously via the Results API and include accepted changes and rejection reasons. Use the results endpoint to retrieve the outcome of submissions.

There are three ways to provide feedback:

• Update information on existing places (e.g., new phone number or hours of operation)
• Add comments to existing places (e.g., "This place is closed" or "The phone is invalid")
• Suggest new places to be added to the business database

Correcting an Attribute

POST /v1/places/submissions

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

For example, to suggest a new phone number and company name for a business with an infogroup_id of "987765321", submit the following request:

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 initial response returns the submission result and ID along with the submitted values. Use the results endpoint to retrieve the outcome of submissions.

{
  "result": "success",
  "id": "5f0b1070c3e4761cabf116bbed2b49c40781a441",
  "infogroup_id": "987765321",
  "attributes": {
    "phone": "(334) 284-9600",
    "name": "Best Pizza in the World"
  }
}

Commenting on an Attribute

Use comments when a value appears incorrect, but no replacement is available.

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

Response:

{
  "result": "success",
  "id": "5f0b2b25c4e164765eed4a245f1a1af940109a87",
  "infogroup_id": "987765321",
  "attributes": {},
  "comments": {
    "phone": "The number seems to be disconnected"
  }
}

Suggesting a New Place

Suggesting a new business requires a core set of attributes as shown below. Optional attributes, such as phone or website, can improve verification time.

Required attributes:

• name
• street
• city
• state
• postal_code

For a complete list of submittable attributes, see Submittable Attributes.

The sample request below shows the minimum required information to suggest a new place:

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "attributes": {
    "name": "Pizza by Bob",
    "street": "123 Main St",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98116",
    "phone": "(206) 123-4567"
  }
}'

The initial response returns the submission result and ID along with the submitted values. The infogroup_id will be null in the response. Use the results endpoint to retrieve the outcome of submissions.

{
  "result": "success",
  "id": "1217186bb4f854511abb1a0869c1d2116b18a26c",
  "infogroup_id": null,
  "attributes": {
    "name": "Pizza by Bob",
    "street": "123 Main St",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98116",
    "phone": "(206) 123-4567"
  }
}

Errors

If the input is invalid or fails validation, a failure result is returned with field-level errors.

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

Result:

{
  "result": "failure",
  "errors": {
    "phone": ["must be 10 digits"]
  },
  "infogroup_id": "987765321",
  "attributes": {
    "phone": "123456"
  }
}

Validation Error Messages

The following validation error messages may be returned for various fields:

Retrieving Results

GET /v1/places/submissions/results

Retrieving results via the Submission Results API consists of:

• Returning results
• Scrolling through changes

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, the current values, and rejected fields with a reason.

Filtering by Submission ID or Infogroup ID

To retrieve results for a specific submission ID or infogroup ID, include the appropriate parameter in the request:

{
  "submission_id": "711e12e0e1577d2d7a65078f0deccd23680b024c",
  "infogroup_id": "939010853",
  "packages": ["core_v1"],
  "fields": ["name", "state"]
}

You can use either submission_id or infogroup_id individually, or combine them to narrow down results.

{
  "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"
    }
  ]
}

Fields

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

{
  "packages": ["core_v1"],
  "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=13835315192676945401741312

JSON request body:

{
  "since": "13835315192676945401741312",
  "packages": ["core_v1"],
  "fields": ["name", "state"]
}

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.

Array Attributes

Array fields represent a list of values. For example, a restaurant may have multiple values for cuisines such as Greek, Mediterranean, and Seafood, or support multiple payment types such as Visa, Mastercard, and Cash.

To update array fields, one of the following keys is required in the request:

Create & Remove Example

Request:

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

Response:

{
  "result": "success",
  "id": "46d0d02dea4d207afe1a19930c206339aa372f41",
  "infogroup_id": "987765321",
  "attributes": {
    "payment_types": {
      "id": "a195b1f5c2a9412c9abc20e1fdca4e40",
      "created_at": "2025-12-13T07:04:38Z",
      "create": ["Cash", "Visa", "Mastercard"],
      "remove": ["Google Checkout"],
      "replace": null
    }
  }
}

Replace Example

Request:

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

Response:

{
  "result": "success",
  "id": "a501580511ab7ef423e703c7e50239a60eb133b3",
  "infogroup_id": "987765321",
  "attributes": {
    "payment_types": {
      "id": "87f7aae855a84850bb780c3b9eabcb3c",
      "created_at": "2025-12-13T07:19:35Z",
      "replace": ["Visa"],
      "create": null,
      "remove": null
    }
  }
}

Nested Attributes

Some fields are collections of objects, where each object contains its own attributes. For example, operating_hours is an array of objects, each defining the days and the start/end times.

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

{
  "infogroup_id": "822562959",
  "attributes": {
    "operating_hours": {
      "create": [
        {"operating_hours.days": ["mon"]},
        {"operating_hours.start_time": "09:00:00"},
        {"operating_hours.start_time": "15:00:00"}
      ]
    }
  }
}

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 a comment is suggested 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"
    }
  ]
}

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

The best way to provide feedback on a duplicate record is to provide a comment to the infogroup_id.

curl https://qa.api.data-axle.com/v1/places/submissions -d '
{
  "infogroup_id": "987765321",
  "comments": {
    "infogroup": "This place is a duplicate of 123456789"
  }
}'

In this example, 123456789 is the record that should remain active.

Submittable Attributes

The following attributes are available for submission. All attributes are optional except when suggesting a new place, which requires: name, street, city, state, and postal_code.

For full attribute definitions and formats, see the Data Dictionary.

Core Business Information

Location Address

Mailing Address

Contact Information

Social Media

Business Classification

Employee & Revenue

Operating Information

Array Attributes

These attributes accept arrays of values using create, remove, or replace operations:

Nested Attributes

These are collections of objects with their own attributes: