API Business Rules

The following business rules govern use of the Contact Export API:

  • Authentication Token: All calls must include a valid access token.
  • Database ID: All API calls must reference the SmashFly Database ID of the database from which contacts should be exported.
  • Web Service response: When successfully exporting a contact record, resume, or list, the system will provide response XML. You can test the API and view sample responses at https://api.smashfly.com/ContactAPI/help; on that page, click the Show Sample link for the related API request. The first response will always include the total number of records to be returned by the call.
  • Returning more than 10,000 Records: Any API calls that must return over 10,000 records at once must use an asynchronous call, which can return up to 250,000 records at one time with no pagination; all contacts will exist in one file that is emailed to the contact email address associated with the Contact Export API Key. Asynchronous calls do not contain contact resumes.
  • SLA: Your organization must have a signed SLA to use this API. The SLA defines the number of records that can be returned per hour; available tiers are described in the next section.

Rate-Limiting Tiers

The number of contacts that can be exported through the API is restricted by the purchased API tier defined by your organizations signed SLA:

Service Level Maximum Number of Records Per Hour
Tier 1 Up to 200; synchronous delivery only
Tier 2

Up to 10,000 (using paginated calls with a hard limit of 1,000 records per call); if the initial call does not include pagination, the initial response will tell the client the following:

  • Total records matching the call criteria
  • Initial Core Limit: 1,000
  • Offset: 0 (starting number)

After the initial call, the API can receive subsequent pagination calls where the caller defines the subsequent core limits and the offset for the next call (for example, start the next 1,000 records returned at row 1,001). This tier does not support asynchronous delivery.

Tier 3

Over 10,000 and up to 250,000 records per call with calls supported every 12 hours; requires asynchronous delivery and will not return contact resumes. The client needs to specify a location where the file will be delivered.
Tier 3+ Requests over the Tier 3 threshold of 250,000 records. Not Supported