Endpoints

Firehose API is designed around the concept of resources, such as a lead, contact or deal. Every resource has its own Firehose endpoint that is used to receive events for particular resource. Each response returns a limited collection of events. The client needs to iteratively call the endpoint in order to drain the event queue.

Event Stream Endpoint

This endpoint retains full event history from the last 72 hours. Any events older than 72 hours will be deleted.


Authentication

All requests to the Firehose API must be authenticated through the standard Authorization header using the Bearer authentication scheme to transmit the access token. See the OAuth 2.0 protocol for more details.

Firehose API user

Important: You can use Firehose API only in the context of the root user. Root user has complete data access on your Base account. To utilize Firehose API you will need to activate Tree Based Permissions on your account and then generate an OAuth Token from your root user’s Base account.


Request Parameters

Firehose API accepts query parameters described in the table below.

Name Description Required Possible Values Default
position Your client position in Firehose stream. yes tail/top/string-from-fh-api -
limit Limits maximum number of events in single response. no 1-100 25

position

The position parameter is required when calling Firehose API. It indicates current client position in the stream that will be used to start consuming events from. When calling Firehose API for the first time you may choose to either start from the beginning of the queue using the tail position (oldest events) or from the end of the queue using the top position (newest events).

Firehose API Stream

Every response will return the next position in the stream, which you will use to make the subsequent call.

limit

Notice that this parameter only enforces the upper limit of events returned in single response. It is not guaranteed to return as many events as the value of the limit in a single response, even if additional data is available.

See Availability contract for more details.


Response Format

Firehose API responses contain collections of events for a particular resource. Each event provides a current snapshot of data along with information regarding what has changed in this singular event and which user enacted the change.

Name Description Type
items A collection of objects the payload carries. collection
meta Payload’s metadata information. object
errors A collection of error objects. collection

Meta

In a successful response, the meta object holds 3 fields:

Name Type Description
links object Link to retrieve next data chunk.
top boolean Tells whether you reached the current end of the stream.
position string Next position to start consuming events from.

Top

This indicator alerts you as to whether or not there is more data available to consume. Notice that new data may appear any time and you should call API periodically even if top is equal to true.

Position

Represents your client position in the stream of changes. It is the client’s responsibility to store the position value. Your workers may fail, so you should retain your position value in non-volatile memory (e.g. a database) in order to begin from the previous position after resumption. Otherwise, you will have to re-initialize your client’s position again. See Consumption Strategies section for more details.

On an error response, the metadata object will hold error-related information such as the http_status and logref attributes.


Items

The items field is always an JSON array. An item represents a single event for the resource. Detailed format of objects depends on which resource type you are requesting.

Each event has standard format that includes two separate sections: data and meta.

Data

Contains current snapshot of the data. See documentation for particular resource to see what data is returned.

Meta

Contains various contextual attributes:

Attribute Type Description
event_id string Unique id generated for every event (e.g. useful for tracing)
event_type string Resource event type, one of: created, updated, deleted.
event_cause string Resource event cause.
event_time string (ISO8601) Date and time of the event.
type string Resource type name.
sequence number Monotonic sequence aligned with order of resource events.
previous object Contains previous values for all the properties that have been modified within particular event.
(available only when event_type equals updated).

sequence

Firehose will attach increasing number (may be not continuous) for each new resource event for particular resource id. It may be used to check which one from two events for same resource id is newer (e.g. to prevent old data processing).

event_cause

Events are typically generated by user interactions. In some cases, events will also be generated by the system itself.

  • interaction - user action.
  • system - admin action (e.g. initial bootstrap) or a backward compatible format change (e.g. new attribute added).
  • embedded_object_event - Firehose will join some resources together (e.g. custom field value in a deal resource references the definition of custom field). In case of delete/update of embedded resource, e.g. if a custom field definition has been deleted/updated, the user may be interested to see the new event for the deal that reflects the change, i.e. a deal with a newly updated name of the custom field. Firehose guarantees that after the embedded object event all subsequent events for the primary resource will contain latest state of the embedded object.

Not all event_cause’s are possible in all event_type’s:

event_type Possible event_cause
created interaction, system
updated interaction, system, embedded_object_event
deleted interaction, system

Important: When calling API using top position, items array is always empty and top is set to true. This is because top request is just used to get current position in the stream of events. This position needs to be used in a subsequent call to get most recent data since the top request was issued.


Pricing And Rate Limiting

The Firehose API will be a premium Base API that is part of the Snap Advanced add-on. Checkout pricing details.