Bulk Retrieval - Partners Only

Overview

This section defines the message specification that will be sent back to the API partners who request a bulk data transfer. The postback message is meant to notify them that their data is ready to pickup and to tell them where to get it.

View current state of a collection of organizations - scheduled bulk file creation/delivery

For results that will be too large to page through, you can schedule bulk file creation/delivery based on a collection id.

The steps to schedule file delivery:

  1. You must set up an endpoint that accepts a response indicating the location of the completed file.
    1. Requests for file delivery are made asynchronously and you will be notified (via your endpoint) when the file is complete and where to pick it up.
    2. Must accept a message that conforms to the Postback Message Specification
  2. Submit a request for a bulk file based on a collection id.
  3. You must specify:
    1. Your PostbackURL (the destination URL to post to when the file is ready - created in Step 1)
    2. The desired file format
    3. The desired file name
  4. Once the file is complete, you will be notified via your endpoint.
    1. This notification message will contain the pickup URL to download the actual file (zipped up).
  5. Issue a GET request to the URL specified in the FileRetrievalURL.

Here are sample API calls to request and retrieve a bulk data file based on collection id:

StepURLHTTP MethodJSON payloadExpected Result
Create a request for a bulk data file based on collection id https://api.bbb.org/api/orgs/bulkdatarequest POST
{ "ResponseOptions": {
	"PostbackURL": "http://mypostbacksite.com/api/BulkDataRequestPostback",
	"Filename": "collection_of_orgs.json",
	"FileFormat": "JSON"
	},	
	"RequestParameters": {
	"CollectionId": 1234
	}
}
200 OK - Successful response Does not guarantee that data will be returned. File will be created asynchronously.
Get bulk data file Once you receive a postback message in your endpoint, issue a GET request to the URL specified in the FileRetrievalURL property of the postback message. https://api.bbb.org/api/orgs/getbulkdatafile?guid=020xcbb1-f2f1-464e-b782-e4dfd62a141e GET None 200 OK File will be downloaded in response as a zip file.

Endpoint

A JSON formatted text body will be sent to the PostbackURL specified in the original request.

EndpointHTTP MethodAuthorization
https://api.bbb.org/api/orgs/bulkdatarequest POST Required

Request Structure

Response options (data structure = "ResponseOptions")

Query parameterData TypeRequired?Description
PostbackURL string Yes URL that will be posted to once the file is ready. Note that the file itself will not be posted, just the information necessary to download the file. Postback Message Specification for Bulk Data Transfers
FileFormat string Yes The type of output file to use. Limited to these options: "JSON", "XML", "TAB"
Filename string Yes Desired filename of the output file. Should include an extension (e.g. .json, .xml, .txt)

Request parameters (data structure = "RequestParameters")

Query parameterData TypeDescription
BusinessId string Internal id of an organization. This is only unique across BBBs/Bureaus. The BusinessId plus the BBBID will make a unique record.
BBBId string Internal identifier of a regional BBB
BBBRating string

Letter grade rating of organization

Valid values:

A, A+, A-, B, B+, B-, C, C+, C-, D, D+, D-, F,NA, NR

IsBBBAccredited boolean Is organization accredited?
StarRatingScore

numeric

 Number between >= 0.00 and <= 5.00

IsReportable

boolean

Is organization reported on the public web site?

OrganizationName

string

One of the names that the organization is known by.

PrimaryOrganizationName

string

The primary name that the organization is known by.

PrimaryCategory

string

The primary category that the organization falls under.

ContactFirstName

string

First name of a known organization contact

ContactLastName

string

Last name of a known organization contact

ContactMiddleName

string

Middle name of a known organization contact

ContactTitle

string

Title of a known organization contact

ContactPrefix

string

Prefix of a known organization contact

Address

string

Street address of one of the organization's locations

City

string

City of one of the organization's locations

StateProvince

string

State/Province of one of the organization's locations

PostalCode

string

Postal code of one of the organization's locations

Phone

string

Phone number of the organization

BusinessURL

string

URL of the organization

ReportURL

string

URL to the organization's BBB Business Review

OrganizationType

string

Type of organization ("Business" or "Charity")

CollectionId

integer

Unique identifier of existing collection. Used to filter results to a set of pre-defined organizations.

OrganizationLastChanged

date/time

Date/time value that indicates when any field on an organization was last changed. Including this value will return all organizations that changed on or after the specified date/time.

RatingLastChanged

date/time

Date/time value that indicates when the rating grade for an organization was last changed. Including this value will return all organizations that changed their rating on or after the specified date/time.

AccreditationStatusLastChanged

date/time

Date/time value that indicates when the accreditation status for an organization was last changed. Including this value will return all organizations that changed their accreditation status on or after the specified date/time.

Responses

The JSON text will contain the following fields:

FieldTypeDescription

RequestId

integer

Council-generated unique id used for tracking the request

FileRetrievalURL

string

URL to retrieve completed file

Username

string

Username that originally requested bulk data file

OriginalRequest

string

Original message text

ExpirationDate

date/time

Date/time in UTC that the file will expire and be unavailable for retrieval

RequestedFileFormat

string

File format of original request

RequestedFilename

string

File name of original request

Possible Return Status Codes

  • 200 OK - Successful response; does not guarantee that data will be returned.
  • 400 Bad Request - Returned if, 1) at least one request parameter is not supplied, 2) an incorrect query parameter is supplied, or 3) reponse parameter options are incorrect.
  • 500 - Internal error

JSON Example

{
"RequestId": 138,
"FileRetrievalURL":"https://api.bbb.org/api/orgs/getbulkdatafile/04be8dd7-e676-4374-9e59-6241325ef6b2",
"Username":"vendor1",
"OriginalRequest":"",
"ExpirationDate":"2016-07-30 14:04:22",
"RequestedFileFormat":"JSON",
"RequestedFilename":"test_json_file.json"
}

Additional Notes