Fishbowl Enterprise Partner API

From Enterprise Help
This is the approved revision of this page, as well as being the most recent.
Jump to: navigation, search

The Fishbowl Enterprise Partner API is available on a limited basis to Fishbowl partners. The information provided here is meant for a technically sophisticated audience. If you are not a developer and you have found yourself on this page, check out our Developer Resources page or the Fishbowl Enterprise API page for an introduction.

The Fishbowl Enterprise API is a RESTful API that fully implements the OData v3 protocol. Any development platform that can make HTTP GET and POST requests can target the API, but OData client libraries—which are available for many different platforms—simplify the development process by an order of magnitude.

Authentication and authorization is provided by OAuth v2, using bearer tokens and either the Authorization Code or Client Credentials grant types. Any development platform that can make HTTPS requests containing custom headers can successfully authenticate with OAuth v2. Various OAuth v2 client libraries are available.

Create, Read, Update, and Delete functionality is available for the following entities:

  • MemberTag (maps Members to their corresponding Tags)
  • Subscription (maps Members to the Lists to which they’re currently subscribed)

Read-only functionality is available for the following entities:

  • ApiClientRequest (categorizes and aggregates counts of requests by API clients; useful for troubleshooting purposes)
  • Brand
  • Category
  • Click (inserted when a Member clicks on any tracked hyperlink in an email message)
  • Group
  • GroupStore
  • Hyperlink (automatically tracked by the Fishbowl system after being automatically discovered within the HTML or text content of a Mailing)
  • MailOpen (inserted when a Member opens an email message and chooses to display images)
  • Message (represents a single email message to a single Member)
  • Site (each Site is a fully autonomous unit with the Fishbowl system)
  • Store
  • SubsciptionEvent (inserted each time a Member subscribe to or unsubscribes from a single List)
  • TriggerLog (inserted each time a Trigger executes, which happens once per day as long as the Trigger is enabled)
  • UserAgent (categorizes device/application/OS data whenever a MailOpen or Click event occurs)

Additionally, there are two methods (“actions” in OData terminology):

  • SendSingleMessage (sends a copy of a Mailing to a single Member in real-time)
  • SendDefaultNotification (after a Member has been inserted or updated, performs whatever action has been configured at the Site level: either send a real-time text-only confirmation message, send a copy of a Triggered Mailing, or take no action)

The endpoint of the API is https://services.fishbowl.com/api/odata/v1, but most requests are Site-specific and require that the appropriate SiteID value is incorporated into the URL (e.g., https://services.fishbowl.com/api/odata/v1/123456 in which “123456” is the SiteID). Metadata about the entities listed above—which can be used by OData client libraries to produce proxy classes—is available at https://services.fishbowl.com/api/odata/v1/$metadata.