Sections:

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:

You must set up an endpoint that accepts a response indicating the location of the completed file.

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.

Must accept a message that conforms to the Postback Message Specification

Submit a request for a bulk file based on a collection id.

You must specify:

Your PostbackURL (the destination URL to post to when the file is ready - created in Step 1)

The desired file format

The desired file name

Once the file is complete, you will be notified via your endpoint.

This notification message will contain the pickup URL to download the actual file (zipped up).

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:

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 parameter

Data Type

Description

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:

Field

Type

Description

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.