Firehose Overview
The Firehose API delivers a continuous stream of data from Sell in near real-time, enabling high volume data integrations and event-driven workflows within Sell or other business systems.
Use Cases
The use case for Firehose differs from REST and Sync APIs due to its key features:
- Provides near real-time integration with high volumes of data
- Captures granular details around each event and data change
- Delivers a complete, sequential stream of events, rather than just the most recent
Automate Processes
The Firehose API can be used to power automations that support complex and unique sales processes within Sell and other business systems, including marketing automation platforms, messaging applications, quoting/contracting solutions and more. These workflows save reps significant time and help close more deals faster by effectively facilitating the sales process and highlighting priorities.
For example, Firehose can be used to change a contact’s deal stage in Sell or create a task for the rep to follow up again at a specific time based on the outcome of a call. Similarly, if a deal is moved to a particular stage in Sell, Firehose can trigger events in other systems such as sending an email or text message, dynamically generating a proposal or creating a support ticket.
Power Business Intelligence
Firehose can also pass a continuous stream of events directly to business intelligence and sales analytics platforms. Event-based data aids in identifying the types of activities that convert the most successfully, the ideal number of touches needed to close a deal, and other actionable insights. It can also be used to fuel real-time sales team performance dashboards.
Generate Alerts
Finally, Firehose can be used to generate alerts within Sell and external systems based on granular information in Sell. For instance, Firehose can power a hot lead notification in Slack, or a reminder via push notification to schedule a meeting or make a call.
Endpoints
Firehose API is designed around the concept of亚博电脑端, 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 provides a stream of changes to Sell data. It retains full event history from the last 72 hours, which you can use to back fill your application if it has been down for some time.
Endpoint
Event stream endpoint:
https://api.getbase.com/v3/:resource/stream
Example
Endpoint that provides event stream for thedeals
resource.
https://api.getbase.com/v3/deals/stream
Authentication
All requests to the Firehose APImustbe authenticated through the standardAuthorization
header using the Bearer authentication scheme to transmit the access token. Seethe OAuth 2.0 protocolfor more details.
Firehose API user
我mportant: You can use Firehose API only in the context of the root user. Root user has complete data access on your Sell account. To utilize Firehose API you will need toactivate Tree Based Permissionson your account and then generate an OAuth Token from your root user’s Sell account.
Authorization: Bearer $ACCESS_TOKEN
Request Parameters
Firehose API accepts query parameters described in the table below.
Name | Description | 要求 | Possible Values | Default |
---|---|---|---|---|
position |
Your client position in Firehose stream. | yes | top /string-from-fh-api/tail |
- |
limit |
Limits maximum number of events in single response. | no | 1-100 | 25 |
position
Theposition
当调用twitter API参数是必需的。我t 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 start from the end of the queue using thetop
position (newest events).
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.
SeeAvailabilitycontract for more details.
First call to Firehose API usingtop
position:
GET /v3_beta/contacts/stream?position=top
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN
User-Agent: $CLIENT_NAME
Read data from the last received position:
GET /v3_beta/contacts/stream?position=WAaHjfuifPIihFHEYoHG
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN
User-Agent: $CLIENT_NAME
Query data from the oldest known position in the stream:
GET /v3_beta/contacts/stream?position=tail
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN
User-Agent: $CLIENT_NAME
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.
Name | Description | Type |
---|---|---|
items |
一个贴画ction of objects the payload carries. | collection |
meta |
Payload's metadata information. | object |
errors |
一个贴画ction of error objects. | collection |
Response envelope:
{
meta:{
links:{
next:“https://api.getbase.com/v3/contacts/stream?position=ZmlyZhvUuZjd&limit=10"
},
top:false,
position:"ZmlyZhvUuZjd"
},
items:[
...
]
}
元
我n a successful response, themeta
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 iftop
is equal totrue
.
Position
Represents your client position in the stream of changes. It is the client's responsibility to store theposition
value. Your workers may fail, so you should retain yourposition
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. SeeConsumption Strategiessection for more details.
On an error response, the metadata object will hold error-related information such as thehttp_status
和logref
attributes.
我tems
Theitems
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
和meta
.
Data
Contains current snapshot of the data. See documentation for particular resource to see what data is returned.
元
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 | Resourceevent 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 equalsupdated ). |
sequence
Firehose will attach increasing number (may be not continuous) for each new resource event for particular resourceid
. It may be used to check which one from two events for same resourceid
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
——用户操作。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 adeal
resource references the definition ofcustom 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 allevent_cause
's are possible in allevent_type
's:
event_type | Possible event_cause |
---|---|
created |
interaction ,system |
updated |
interaction ,system ,embedded_object_event |
deleted |
interaction ,system |
Example of the request and response:
GET /v3/contacts/stream?position=tail
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN
User-Agent: $CLIENT_NAME
HTTP/1.1200好吧
Content-Type:application/json
{
"meta":{
"links":{
"next":“https://api.getbase.com/v3/contacts/stream?position=ZmlyZWhvc2Uu"
},
"position":"ZmlyZWhvc2Uu",
"top":false
},
"items":[
{
"data":{
"owner_id":238218,
"created_at":"2016-07-01T08:35:13Z",
"first_name":"Eric",
"email":"[email protected]",
"last_name":"Smith",
"tags":[
{
"data":{
"name":"green",
"resource_type":"contact",
"id":514485
},
"meta":{
"type":"tag"
}
}
],
...
},
"meta":{
"event_id":"1JNXUtNUQwqHT6uPk97veQ",
"event_time":"2016-08-22T15:14:23Z"
"event_cause":"interaction",
"sequence":175,
"event_type":"updated",
"type":"contact",
"previous":{
"tags":[]
}
}
},
{
"data":{
...
},
"meta":{
...
}
}
]
}
我mportant:When calling API usingtop
position,items
array is always empty andtop
is set totrue
. This is becausetop
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 thetop
request was issued.
Example of the response for thetop
request:
GET/v3/contacts/stream?position=top
Accept:application/json
Authorization:持票人$ACCESS_TOKEN
User-Agent:$CLIENT_NAME
HTTP/1.1200好吧
Content-Type:application/json
{
"meta":{
"links":{
"next":“https://api.getbase.com/v3/contacts/stream?position=ZmlyZWhvc2Uu"
},
"position":"ZmlyZWhvc2Uu",
"top":true
},
"items":[]
}
Pricing And Rate Limiting
The Firehose API is a premium Sell API that is part of the Snap Advanced add-on. Checkoutpricing details.