API Documentation
Integrate StoneShot data with your website, CRM, CMS and much more to implement smarter marketing strategies and give your clients a personalised experience. Here is everything you need to get started.
Getting started
Authentication
The StoneShot API currently supports authentication via an API Key using basic HTTP Authentication. You can generate your API key from the Integrations page when logged into your StoneShot account. When making an API request you will provide your API key (Base64 encoded) as the password, the username value can be left empty as it is not used for authentication.
To quickly test calls to the API with your API key, you can use a tool such as cURL via the command line. You’ll find cURL examples for each method in the following guide. Here’s an example of a cURL request to the ping endpoint to check the current status of the API.
curl -L -X GET \
"https://api.stoneshot.com/v1/ping" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"
Requests
Requests to the StoneShot API are formed based on a number of rules and parameters. Full details of the supported parameters for each request are detailed in the documentation below. Here is a description of each of the key pieces that make up a request to the API.
Root
All requests to the StoneShot API will stem from the API root:
https://api.stoneshot.com/v1/Path parameters
Path parameters are required when targeting a specific record, here’s an example of a request endpoint to retrieve a specific list, in this case [list_id] is the path parameter.
https://api.stoneshot.com/v1/lists/[list_id]Query parameters
Query parameters are used in requests to the API to restrict the properties returned in a given request by explicitly including those fields as part of the ‘select’ query parameter. By default the common fields will be returned as part of any request, the ‘select’ query parameter can be included if the defaults do not cover your needs. A ‘select’ query string should be included for each field required.
Here’s an example of the ‘select’ query parameter being used to only bring back the name field when retrieving all lists.
https://api.stoneshot.com/v1/lists?select=nameQuery parameters can also be used to filter, sort and limit results. Examples of using these query parameters can be found within each request detail in the following documentation. Here’s an example of a request to get no more than 50 lists with ‘StoneShot’ in the name sorted by most recently created.
https://api.stoneshot.com/v1/lists?name=stoneshot&count=50&sort_by=-create_date_utcBody parameters
Body parameters are often required for POST and PATCH requests to the StoneShot API. The body of the request should be in JSON format, examples of body parameters can be found in the cURL snippets for each of the requests in the following documentation. Here’s a short example of the body required to create a new static list.
{
"name": "StoneShot API List",
"tags":[
{
"name": "api"
}
],
"teams":[
{
"name": "StoneShot"
}
]
}Responses
API responses are served in JSON (JavaScript Object Notation) format. This includes both success and error responses.
Example responses are given for each request in the following documentation.
Response status codes
Each request to the API will return a response partnered by a HTTP status code representing the status of the request. A successful request will return a HTTP Status 200 response and the relevant response object. For example when creating a list via the API, on successful create you will receive a HTTP status 200 and the newly created list object in the response.
Requests that fail will return the relevant HTTP status code along with a custom response code and message which will provide more detail on the error itself. Here’s an example of an error returned when an invalid API key is offered.
{
"code": 104,
"message": "Invalid key"
}Rate limiting
The StoneShot API endpoints are subject to rate limiting based on the number of requests over a period of time. The default rate is limit 10,000 requests every 60 minutes.
Requests made to the API once the limit has been reached, will return a response such as below, the response headers will include additional information on the your rate limit and the time at which it is reset. If you find that you are regularly hitting the limit, please contact StoneShot support to discuss your options.
X-Rate-Limit-Limit: 10000
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: "17/01/2020 17:43:25"
{
"code": 114,
"message": "Too many requests in time frame; check RateLimit headers"
}Contact matching
A number of the API requests will involve retrieving or updating an existing contact record. The API supports a number of individual StoneShot fields in order to determine which contact to match on, these fields being:
- Member Url Id
- StoneShot Contact Id
- CRM ID (SalesforceId, Microsoft Dynamics Id, Siebel Id or Unique User Id)
- Email Address (Cannot be used as a path parameter)
When one of the seven identifiers is required in a request to the API, it should be passed through using the ‘identifier’ keyword. The matching criteria will then be determined automatically as part of the request.
Campaigns
Retrieve your contacts who have been sent a campaign or send a campaign to your contacts.
Get campaigns
More
Less
GET/campaigns
Retrieve campaigns associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
campaign_idnamedate_sent_utcsendstotal_openstotal_clicksbouncesreachopt_outsopen_rate_%click_rate_%click_to_open_rate_%delivery_rate_%last_open_or_click_date_utccommunication_typeaudiencetags.nameis_ab
Other fields
subjectfrom_emailfrom_nameunique_opensunique_desktop_opensunique_mobile_opensunique_other_opensunique_clicksunique_desktop_clicksunique_mobile_clicksunique_other_clicksdesktop_opensmobile_opensother_opensdesktop_clicksmobile_clicksother_clicksdesktop_glancesdesktop_skimsdesktop_readsdesktop_opens_unknown_lengthmobile_glancesmobile_skimsmobile_readsmobile_opens_unknown_lengthdesktop_open_rate_%mobile_open_rate_%engagement_glanced_%engagement_skimmed_%engagement_read_%bounce_rate_%form_submissionstags.tag_idproductlist_namefolder_idcampaign_codecampaignab
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is campaign_id descending.
name
Restrict results based on campaign name.
tag
Restrict results based on campaigns with a given tag.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"campaigns": [
{
"campaign_id": 0,
"name": "string",
"date_sent_utc": "2019-06-13T15:00:45Z",
"sends": 0,
"total_opens": 0,
"total_clicks": 0,
"bounces": 0,
"reach": 0,
"opt-outs": 0,
"open_rate_%": 0.0,
"click_rate_%": 0.0,
"click_to_open_rate_%": 0.0,
"delivery_rate_%": 0.0,
"last_open_or_click_date_utc": "2019-06-13T15:00:45Z",
"tags": [
{
"name": "string"
}
],
"communication_type": "string",
"audience": "string",
"is_ab": bool
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get campaign
More
Less
GET/campaigns/{campaign_id}
Get information for a specific campaign in your account.
Path parameters
campaign_id
The unique StoneShot campaign id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
campaign_idnamedate_sent_utcsendstotal_openstotal_clicksbouncesreachopt_outsopen_rate_%click_rate_%click_to_open_rate_%delivery_rate_%last_open_or_click_date_utccommunication_typeaudiencetags.nameis_ab
Other fields
subjectfrom_emailfrom_nameunique_opensunique_desktop_opensunique_mobile_opensunique_other_opensunique_clicksunique_desktop_clicksunique_mobile_clicksunique_other_clicksdesktop_opensmobile_opensother_opensdesktop_clicksmobile_clicksother_clicksdesktop_glancesdesktop_skimsdesktop_readsdesktop_opens_unknown_lengthmobile_glancesmobile_skimsmobile_readsmobile_opens_unknown_lengthdesktop_open_rate_%mobile_open_rate_%engagement_glanced_%engagement_skimmed_%engagement_read_%bounce_rate_%form_submissionstags.tag_idhtml_share_linktext_share_linkproductlist_namefolder_idcampaign_codecampaignab
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"campaign": [
{
"campaign_id": 0,
"name": "string",
"date_sent_utc": "2019-06-13T15:00:45Z",
"sends": 0,
"total_opens": 0,
"total_clicks": 0,
"bounces": 0,
"reach": 0,
"opt-outs": 0,
"open_rate_%": 0.0,
"click_rate_%": 0.0,
"click_to_open_rate_%": 0.0,
"delivery_rate_%": 0.0,
"last_open_or_click_date_utc": "2019-06-13T15:00:45Z",
"tags": [
{
"name": "string"
}
],
"communication_type": "string",
"audience": "string",
"is_ab": bool
}
]
}Error response
{
"code": "117",
"message": "No data found"
}Get campaign contacts
More
Less
GET/campaigns/{campaign_id}/contacts
Get contacts who have been sent a specified campaign.
Path parameters
campaign_id
The unique StoneShot campaign id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
emailtitlefirst_namelast_namecompanycreate_date_utccontact_idlast_active_utc
Other fields
middle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlcreate_date_utcis_bouncesalesforce_account_idsalesforce_owner_iddouble_opt_in_statusunique_user_idsalesforce_idsiebel_iddynamics_idsegments.segment_idsegments.namesegments.segmentation.namesegments.segmentation.segmentation_idemail_preferences.segment_idemail_preferences.nameemail_preferences.segmentation.nameemail_preferences.segmentation.segmentation_idcontent_preferences.content_tag_idcontent_preferences.tag.tag_idcontent_preferences.tag.nameevents.segment_idevents.nameevents.segmentation.nameevents.segmentation.segmentation_idevents.session.session_idevents.session.locationevents.session.event.event_idevents.session.event.namedocument_preferences.segment_iddocument_preferences.namedocument_preferences.segmentation.namedocument_preferences.segmentation.segmentation_id
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guid
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guid
count
The number of records to return. The default value is 100; maximum allowed value is 500.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is contact_id descending.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/contacts" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2019-06-13T15:00:45Z",
"last_active_utc": "2020-08-06T15:03:10Z"
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get campaign sends
More
Less
GET/campaigns/{campaign_id}/sends
Get sends for a specified campaign.
Path parameters
campaign_id
The unique StoneShot campaign id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
send_date_utccontact.emailcontact.titlecontact.first_namecontact.last_namecontact.companycontact.create_date_utccontact.contact_idcontact.last_active_utc
Other fields
contact.middle_namecontact.websitecontact.job_titlecontact.telephonecontact.telephone_extcontact.faxcontact.mobile_numbercontact.home_numbercontact.address_1contact.address_2contact.address_3contact.address_4contact.citycontact.countycontact.postcodecontact.countrycontact.opt_incontact.custom_1contact.custom_2contact.custom_3contact.custom_4contact.custom_5contact.custom_6contact.custom_7contact.custom_8contact.custom_9contact.custom_10contact.custom_11contact.custom_12contact.prefer_htmlcontact.is_bouncecontact.salesforce_account_idcontact.salesforce_owner_idcontact.unique_user_idcontact.salesforce_idcontact.siebel_idcontact.dynamics_idcontact_guid
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is send_date_utc descending.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/sends" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"sends": [
{
"send_date_utc": "2019-06-13T15:00:45Z",
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-10-07T19:03:11Z",
"last_active_utc": "2020-12-22T16:29:30Z"
}
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get campaign opens
More
Less
GET/campaigns/{campaign_id}/opens
Get opens for a specified campaign.
Path parameters
campaign_id
The unique StoneShot campaign id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
open_date_utcdevice.namedevice.typecontact.emailcontact.titlecontact.first_namecontact.last_namecontact.companycontact.create_date_utccontact.contact_idcontact.last_active_utc
Other fields
contact.middle_namecontact.websitecontact.job_titlecontact.telephonecontact.telephone_extcontact.faxcontact.mobile_numbercontact.home_numbercontact.address_1contact.address_2contact.address_3contact.address_4contact.citycontact.countycontact.postcodecontact.countrycontact.opt_incontact.custom_1contact.custom_2contact.custom_3contact.custom_4contact.custom_5contact.custom_6contact.custom_7contact.custom_8contact.custom_9contact.custom_10contact.custom_11contact.custom_12contact.prefer_htmlcontact.is_bouncecontact.salesforce_account_idcontact.salesforce_owner_idcontact.unique_user_idcontact.salesforce_idcontact.siebel_idcontact.dynamics_idcontact_guid
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is open_date_utc descending.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/opens" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"opens": [
{
"open_date_utc": "2019-06-13T15:00:45Z",
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-10-07T19:03:11Z",
"last_active_utc": "2020-12-22T16:29:30Z"
}
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get campaign opens for a specific contact
More
Less
GET/campaigns/{campaign_id}/opens/contacts/{identifier}
Get opens for a contact in a specified campaign.
Path parameters
campaign_id
The unique StoneShot campaign id.
identifier
A unique identifier for the contact. See contact matching for a list of the supported identifiers.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
opens.open_date_utcopens.device.nameopens.device.typeemailtitlefirst_namelast_namecompanycreate_date_utccontact_idlast_active_utc
Other fields
middle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlis_bouncesalesforce_account_idsalesforce_owner_idunique_user_idsalesforce_idsiebel_iddynamics_idcontact_guid
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/opens/contacts/[identifier]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2017-05-17T11:09:07Z",
"last_active_utc": "2021-01-05T15:24:14Z",
"opens": [
{
"open_date_utc": "2020-12-03T15:40:26Z",
"device": {
"name": "string",
"type": "string"
}
}
]
}
}Error response
{
"code": "117",
"message": "No data found"
}Get campaign clicks
More
Less
GET/campaigns/{campaign_id}/clicks
Get clicks for a specified campaign.
Path parameters
campaign_id
The unique StoneShot campaign id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
click_date_utcurldevice.namedevice.typecontact.emailcontact.titlecontact.first_namecontact.last_namecontact.companycontact.create_date_utccontact.contact_idcontact.last_active_utc
Other fields
link_idcontact.middle_namecontact.websitecontact.job_titlecontact.telephonecontact.telephone_extcontact.faxcontact.mobile_numbercontact.home_numbercontact.address_1contact.address_2contact.address_3contact.address_4contact.citycontact.countycontact.postcodecontact.countrycontact.opt_incontact.custom_1contact.custom_2contact.custom_3contact.custom_4contact.custom_5contact.custom_6contact.custom_7contact.custom_8contact.custom_9contact.custom_10contact.custom_11contact.custom_12contact.prefer_htmlcontact.is_bouncecontact.salesforce_account_idcontact.salesforce_owner_idcontact.unique_user_idcontact.salesforce_idcontact.siebel_idcontact.dynamics_id
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is click_date_utc descending.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/clicks" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"clicks": [
{
"click_date_utc": "2019-06-13T15:00:45Z",
"url": "string",
"device": {
"name": "string",
"type": "string"
},
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-10-07T19:03:11Z",
"last_active_utc": "2020-12-22T16:29:30Z"
}
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get campaign clicks for a specific contact
More
Less
GET/campaigns/{campaign_id}/clicks/contacts/{identifier}
Get clicks for a contact in a specified campaign.
Path parameters
campaign_id
The unique StoneShot campaign id.
identifier
A unique identifier for the contact. See contact matching for a list of the supported identifiers.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
clicks.click_date_utcclicks.urlclicks.device.nameclicks.device.typeemailtitlefirst_namelast_namecompanycreate_date_utccontact_idlast_active_utc
Other fields
clicks.link_idmiddle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlis_bouncesalesforce_account_idsalesforce_owner_idunique_user_idsalesforce_idsiebel_iddynamics_idcontact_guid
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/clicks/contacts/[identifier]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2017-05-17T11:09:07Z",
"last_active_utc": "2021-01-05T15:24:14Z",
"clicks": [
{
"click_date_utc": "2020-12-03T15:40:26Z",
"url": "string",
"device": {
"name": "string",
"type": "string"
}
}
]
}
}Error response
{
"code": "117",
"message": "No data found"
}Get campaign links
More
Less
GET/campaigns/{campaign_id}/links
Get links for a specified campaign.
Path parameters
campaign_id
The unique StoneShot campaign id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
link_idurltracked_urltypetotal_clicksunique_clicks
Other fields
tags.tag_idtags.name
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is link_id descending.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/links" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"links": [
{
"link_id": 0,
"url": "string",
"tracked_url": "string",
"type": "string",
"total_clicks": 0,
"unique_clicks": 0
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get campaign unsubscribes
More
Less
GET/campaigns/{campaign_id}/unsubscribes
Get unsubscribes for a specified campaign.
Path parameters
campaign_id
The unique StoneShot campaign id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
unsubscribe_date_utccontact.emailcontact.titlecontact.first_namecontact.last_namecontact.companycontact.create_date_utccontact.contact_idcontact.last_active_utc
Other fields
contact.middle_namecontact.websitecontact.job_titlecontact.telephonecontact.telephone_extcontact.faxcontact.mobile_numbercontact.home_numbercontact.address_1contact.address_2contact.address_3contact.address_4contact.citycontact.countycontact.postcodecontact.countrycontact.opt_incontact.custom_1contact.custom_2contact.custom_3contact.custom_4contact.custom_5contact.custom_6contact.custom_7contact.custom_8contact.custom_9contact.custom_10contact.custom_11contact.custom_12contact.prefer_htmlcontact.is_bouncecontact.salesforce_account_idcontact.salesforce_owner_idcontact.unique_user_idcontact.salesforce_idcontact.siebel_idcontact.dynamics_idcontact.contact_guid
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is unsubscribe_date_utc descending.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/unsubscribes" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"unsubscribes": [
{
"unsubscribe_date_utc": "2019-06-13T15:00:45Z",
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-10-07T19:03:11Z",
"last_active_utc": "2020-12-22T16:29:30Z"
}
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Add contact to campaign
More
Less
PATCH/campaigns/{campaign_id}/contacts
Send a contact an email by adding them to an existing campaign using any of the unique contact ids.
Path parameters
campaign_id
The unique StoneShot campaign id.
Body parameters
member_url_idstring
The contact member url (optional)
salesforce_idstring
The contact salesforce id (optional).
dynamics_idstring
The contact microsoft dynamics id (optional).
siebel_idstring
The contact siebel id (optional).
unique_user_idstring
The contact unique external user id (optional).
contact_idinteger
The unique StoneShot contact id (optional).
emailstring
The contact email address (optional).
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/campaigns/[campaign_id]/contacts"
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string"}'
Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2019-06-13T15:00:45Z",
"last_active_utc": "2020-08-06T15:03:10Z"
}
]
}Error response
{
"code": "117",
"message": "No data found"
}Contacts
Retrieve your StoneShot contacts information, create or update contacts and more.
Get contacts
More
Less
GET/contacts
Retrieve contacts associated with your account.
Request parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
emailtitlefirst_namelast_namecompanycreate_date_utccontact_id
Other fields
middle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlcreate_date_utcis_bouncesalesforce_account_idsalesforce_owner_iddouble_opt_in_statusunique_user_idsalesforce_idsiebel_iddynamics_idsegments.segment_idsegments.namesegments.segmentation.namesegments.segmentation.segmentation_idemail_preferences.segment_idemail_preferences.nameemail_preferences.segmentation.nameemail_preferences.segmentation.segmentation_idcontent_preferences.content_tag_idcontent_preferences.tag.tag_idcontent_preferences.tag.nameevents.segment_idevents.nameevents.segmentation.nameevents.segmentation.segmentation_idevents.session.session_idevents.session.locationevents.session.event.event_idevents.session.event.namedocument_preferences.segment_iddocument_preferences.namedocument_preferences.segmentation.namedocument_preferences.segmentation.segmentation_id
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guidlast_active_utclast_update_date_utc
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guidlast_active_utclast_update_date_utc
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is contact_id descending.
email
Restrict results based on the email address.
title
Restrict results based on the title.
first_name
Restrict results based on the first name.
last_name
Restrict results based on the last name.
company
Restrict results based on the company.
job_title
Restrict results based on the job title.
city
Restrict results based on the city.
county
Restrict results based on the county.
country
Restrict results based on the country.
last_update_date_utc
Only retrieve contacts that have been updated on or before this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/contacts" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"
Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-01-09T15:12:17Z"
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Create contact
More
Less
POST/contacts
Create a new contact against your account.
Body parameters
emailstring
The email address of the contact.
titlestring
The title of the contact.
first_namestring
The first name of the contact
last_namestring
The last name of the contact
job_titlestring
The job title of the contact.
companystring
The company of the contact.
opt_inboolean
The opt-in status of the contact.
prefer_htmlboolean
The preferred email format for the contact to receive.
address_1string
The address line 1 of the contact.
address_2string
The address line 2 of the contact.
address_3string
The address line 3 of the contact.
address_4string
The address line 4 of the contact.
citystring
The city of the contact.
countystring
The county of the contact.
countrystring
The country of the contact.
postcodestring
The postcode of the contact.
telephonestring
The telephone of the contact.
telephone_extstring
The telephone extension of the contact.
mobile_numberstring
The mobile telephone number of the contact.
home_numberstring
The home telephone number of the contact.
faxstring
The fax number of the contact.
websitestring
The website of the contact.
unique_user_idstring
The external unique user id of the contact.
salesforce_idstring
The salesforce id of the contact.
siebel_idstring
The siebel id of the contact.
microsoft_dynamics_idstring
The microsoft dynamics id of the contact.
custom_1string
The custom 1 of the contact.
segmentationsobject
The segmentation values for the contact.
email_preferencesobject
The email preference values for the contact.
eventsobject
The event session statuses for the contact.
document_preferencesobject
The document preference values for the contact.
content_preferencesobject
The content preference values for the contact.
custom_fieldsobject
The custom field values for the contact.
double_opt_in_statusinteger
The double opt-in status of the contact.
cURL example
curl -L -X POST \
"https://api.stoneshot.com/v1/contacts" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string", "first_name": "string", "last_name": "string", "segmentations": [{ "segmentation_id": integer, "segment_id": integer }], "email_preferences": [{ "segmentation_id": integer, "segment_id": integer }], "events": [{ "segmentation_id": integer, "segment_id": integer }] , "document_preferences": [{ "segmentation_id": integer, "segment_id": integer }], "content_preferences": [{ "tag_id": integer }], "custom_fields": [{ "custom_field_id": integer, "value": "string" }]}'
Success response
{
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-01-09T15:12:17Z",
"last_active_utc": "2020-01-09T15:12:17Z"
}
}Error response
{
"code": "119",
"message": "Invalid email address"
}Get contact
More
Less
GET/contacts/{identifier}
Get information for a specific contact record in your account.
Path parameters
identifier
A unique identifier for the contact. See contact matching for a list of the supported identifiers.
Request parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
emailtitlefirst_namelast_namecompanycreate_date_utccontact_idlast_active_utc
Other fields
middle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlcreate_date_utcis_bouncesalesforce_account_idsalesforce_owner_iddouble_opt_in_statusunique_user_idsalesforce_idsiebel_iddynamics_idsegments.segment_idsegments.namesegments.segmentation.namesegments.segmentation.segmentation_idemail_preferences.segment_idemail_preferences.nameemail_preferences.segmentation.nameemail_preferences.segmentation.segmentation_idcontent_preferences.content_tag_idcontent_preferences.tag.tag_idcontent_preferences.tag.nameevents.segment_idevents.nameevents.segmentation.nameevents.segmentation.segmentation_idevents.session.session_idevents.session.locationevents.session.event.event_idevents.session.event.namedocument_preferences.segment_iddocument_preferences.namedocument_preferences.segmentation.namedocument_preferences.segmentation.segmentation_id
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guidlast_update_date_utc
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guidlast_update_date_utc
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/contacts/[identifier]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"
Success response
{
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-01-09T15:12:17Z",
"last_active_utc": "2020-01-09T15:12:17Z"
}
}Error response
{
"code": "117",
"message": "No data found"
}Update contact
More
Less
PATCH/contacts/{identifier}
Update a contact record in your account.
Path parameters
identifier
A unique identifier for the contact. See contact matching for a list of the supported identifiers.
Body parameters
emailstring
The email address of the contact.
titlestring
The title of the contact.
first_namestring
The first name of the contact
last_namestring
The last name of the contact
job_titlestring
The job title of the contact.
companystring
The company of the contact.
opt_inboolean
The opt-in status of the contact.
prefer_htmlboolean
The preferred email format for the contact to receive.
address_1string
The address line 1 of the contact.
address_2string
The address line 2 of the contact.
address_3string
The address line 3 of the contact.
address_4string
The address line 4 of the contact.
citystring
The city of the contact.
countystring
The county of the contact.
countrystring
The country of the contact.
postcodestring
The postcode of the contact.
telephonestring
The telephone of the contact.
telephone_extstring
The telephone extension of the contact.
mobile_numberstring
The mobile telephone number of the contact.
home_numberstring
The home telephone number of the contact.
faxstring
The fax number of the contact.
websitestring
The website of the contact.
unique_user_idstring
The external unique user id of the contact.
salesforce_idstring
The salesforce id of the contact.
siebel_idstring
The siebel id of the contact.
microsoft_dynamics_idstring
The microsoft dynamics id of the contact.
custom_1string
The custom 1 of the contact.
segmentationsobject
The segmentation values for the contact.
email_preferencesobject
The email preference values for the contact.
eventsobject
The event session statuses for the contact.
document_preferencesobject
The document preference values for the contact.
content_preferencesobject
The content preference values for the contact.
custom_fieldsobject
The custom field values for the contact.
double_opt_in_statusinteger
The double opt-in status of the contact.
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/contacts/[identifier]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string", "first_name": "string", "last_name": "string", "segmentations": [{ "segmentation_id": integer, "segment_id": integer }], "email_preferences": [{ "segmentation_id": integer, "segment_id": integer }], "events": [{ "segmentation_id": integer, "segment_id": integer }] , "document_preferences": [{ "segmentation_id": integer, "segment_id": integer }], "content_preferences": [{ "tag_id": integer }], "custom_fields": [{ "custom_field_id": integer, "value": "string" }]}'
Success response
{
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-01-09T15:12:17Z",
"last_active_utc": "2020-01-09T15:12:17Z"
}
}Error response
{
"code": "117",
"message": "No data found"
}Create or Update contact
More
Less
POST/contacts/createOrUpdate
Create a new contact against your account, or update if that contact already exists, based on email address.
Body parameters
emailstring
The email address of the contact. (Required)
titlestring
The title of the contact.
first_namestring
The first name of the contact
last_namestring
The last name of the contact
job_titlestring
The job title of the contact.
companystring
The company of the contact.
opt_inboolean
The opt-in status of the contact.
prefer_htmlboolean
The preferred email format for the contact to receive.
address_1string
The address line 1 of the contact.
address_2string
The address line 2 of the contact.
address_3string
The address line 3 of the contact.
address_4string
The address line 4 of the contact.
citystring
The city of the contact.
countystring
The county of the contact.
countrystring
The country of the contact.
postcodestring
The postcode of the contact.
telephonestring
The telephone of the contact.
telephone_extstring
The telephone extension of the contact.
mobile_numberstring
The mobile telephone number of the contact.
home_numberstring
The home telephone number of the contact.
faxstring
The fax number of the contact.
websitestring
The website of the contact.
unique_user_idstring
The external unique user id of the contact.
salesforce_idstring
The salesforce id of the contact.
siebel_idstring
The siebel id of the contact.
microsoft_dynamics_idstring
The microsoft dynamics id of the contact.
custom_1string
The custom 1 of the contact.
segmentationsobject
The segmentation values for the contact.
email_preferencesobject
The email preference values for the contact.
eventsobject
The event session statuses for the contact.
document_preferencesobject
The document preference values for the contact.
content_preferencesobject
The content preference values for the contact.
custom_fieldsobject
The custom field values for the contact.
double_opt_in_statusinteger
The double opt-in status of the contact.
cURL example
curl -L -X POST \
"https://api.stoneshot.com/v1/contacts/createOrUpdate" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string", "first_name": "string", "last_name": "string", "segmentations": [{ "segmentation_id": integer, "segment_id": integer }], "email_preferences": [{ "segmentation_id": integer, "segment_id": integer }], "events": [{ "segmentation_id": integer, "segment_id": integer }] , "document_preferences": [{ "segmentation_id": integer, "segment_id": integer }], "content_preferences": [{ "tag_id": integer }], "custom_fields": [{ "custom_field_id": integer, "value": "string" }]}'
Success response
{
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-01-09T15:12:17Z",
"last_active_utc": "2020-01-09T15:12:17Z"
}
}Error response
{
"code": "119",
"message": "Invalid email address"
}Get contact campaign activity
More
Less
GET/campaigns/activity/contacts/{identifier}
Retrieve all historic campaign activity for a contact associated with your account.
Path parameters
identifier
A unique identifier for the contact. See contact matching for a list of the supported identifiers.
Request parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
emailtitlefirst_namelast_namecompanycreate_date_utccontact_idlast_active_utccampaign_activity.activity_date_utccampaign_activity.typecampaign_activity.campaign.campaign_idcampaign_activity.campaign.name
Other fields
middle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlis_bouncesalesforce_account_idsalesforce_owner_iddouble_opt_in_statusunique_user_idsalesforce_idsiebel_iddynamics_idcampaign_activity.campaign.date_sent_utccampaign_activity.campaign.from_namecampaign_activity.campaign.from_emailcampaign_activity.campaign.subjectcampaign_activity.activity_idcampaign_activity.url_clickedcampaign_activity.read_secondscontact_guid
campaign_id
Restrict results based on campaign ID.
campaign_name
Restrict results based on campaign name.
tag
Restrict results based on campaigns with a given tag.
from_date_utc
Only retrieve activity that occurred on or after this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
to_date_utc
Only retrieve activity that occurred on or before this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/campaigns/activity/contacts/[identifier]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"
Success response
{
"contact": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-01-09T15:12:17Z",
"last_active_utc": "2020-01-09T15:12:17Z",
"campaign_activity": [
{
"activity_date_utc": "2020-01-09T15:12:17Z",
"type": "string",
"campaign": {
"campaign_id": 0,
"name": "string"
}
}
]
}
]
}Error response
{
"code": "117",
"message": "No data found"
}Content distribution system
Your StoneShot content preferences, used for managing contact content preferences.
Get content preferences
More
Less
GET/content-preferences
Retrieve all content preferences against your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
content_tag_iddisplay_ordertag.tag_idtag.name
Other fields
enabledvisiblegroup_iddescription
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is id descending.
name
Restrict results based on the content preference name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/content-preferences" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"content_preferences": [
{
"content_tag_id": 0,
"display_order": 0,
"tag": {
"tag_id": 0,
"name": "string"
}
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get content preference
More
Less
GET/content-preferences/{content_tag_id}
Get information for a specific content preference in your account.
Path parameters
content_tag_id
The unique StoneShot content tag id.
Request parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
content_tag_iddisplay_ordertag.tag_idtag.name
Other fields
enabledvisiblegroup_iddescription
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/content-preferences/[content_tag_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"
Success response
{
"content_preference": {
"content_tag_id": 0,
"display_order": 0,
"tag": {
"tag_id": 0,
"name": "string"
}
}
}Error response
{
"code": "117",
"message": "No data found"
}Update content preference
More
Less
PATCH/content-preferences/{content_tag_id}
Update a content tag preference in your account.
Path parameters
content_tag_id
The unique StoneShot content tag id.
Body parameters
namestring
The name of the content tag preference.
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/content-preferences/[content_tag_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"name": "string"}'
Success response
{
"content_preference": {
"content_tag_id": 0,
"display_order": 0,
"tag": {
"tag_id": 0,
"name": "string"
}
}
}Error response
{
"code": "122",
"message": "That record already exists"
}Contact custom fields
Your StoneShot contact custom fields, used for storing custom contact information.
Get contact custom fields
More
Less
GET/custom-fields
Retrieve all contact custom fields against your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
custom_field_idnamedisplay_namedisplay_ordercreated_at_utc
Other fields
allow_html
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is id descending.
name
Restrict results based on the custom field name.
display_name
Restrict results based on the custom field display name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/custom-fields" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"custom_fields": [
{
"custom_field_id": 0,
"name": "string",
"display_name": "string",
"display_order": 0,
"created_at_utc": "2020-01-17:43:25Z"
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Document distribution system
Your StoneShot fund document preferences, used for managing contact fund document preferences.
Get document preferences
More
Less
GET/document-preferences
Retrieve all document preferences against your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
document_fund_idnamerange.range_idrange.namedocuments.document_iddocuments.external_iddocuments.namedocuments.urldocuments.last_updated_utcdocuments.subscribed_iddocuments.unsubscribed_id
Other fields
alt_namedocuments.system_namedocuments.segmentation_iddocuments.isindocuments.sedoldocuments.alt_namedocuments.description
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is document_fund_id descending.
name
Restrict results based on the document fund name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/document-preferences" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"document_preferences": [
{
"document_fund_id": 2510,
"name": "PAICR_2018",
"url": null,
"subscribed_id": null,
"unsubscribed_id": null,
"last_updated_utc": "2018-09-27T15:27:25Z",
"range": null,
"documents": [
{
"document_id": 11446,
"name": "StoneShot_MA-TheGood-TheBad-TheUgly_BOSTON",
"url": "",
"last_updated_utc": "2018-09-27T15:26:38Z",
"external_id": null,
"subscribed_id": 457506,
"unsubscribed_id": 457507
}
]
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Email preferences
Your StoneShot email preferences, used for managing contact preferences.
Get email preferences
More
Less
GET/email-preferences
Retrieve all email preferences against your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
segmentation_idnamedisplay_ordersegments.segment_idsegments.namesegments.display_order
Other fields
dynamic_system_namesegments.detailssegments.dynamic_from_emailsegments.dynamic_from_name
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is segmentation_id descending.
name
Restrict results based on the email preference name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/email-preferences" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"email_preferences": [
{
"segmentation_id": 0,
"name": "string",
"display_order": 0,
"segments": [
{
"segment_id": 0,
"name": "string",
"display_order": 0
},
{
"segment_id": 0,
"name": "string",
"display_order": 0
}
]
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get email preference
More
Less
GET/email-preferences/{segmentation_id}
Get information for a specific email preference in your account.
Path parameters
segmentation_id
The unique StoneShot email preference id.
Request parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
segmentation_idnamedisplay_ordersegments.segment_idsegments.namesegments.display_order
Other fields
dynamic_system_namesegments.detailssegments.dynamic_from_emailsegments.dynamic_from_name
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/email-preferences/[segmentation_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"
Success response
{
{
"email_preference": {
"segmentation_id": 0,
"name": "string",
"display_order": 0,
"segments": [
{
"segment_id": 0,
"name": "string",
"display_order": 0
}
]
}
}
}Error response
{
"code": "117",
"message": "No data found"
}Update email preference
More
Less
PATCH/email-preferences/{segmentation_id}
Update an email preference in your account.
Path parameters
segmentation_id
The unique StoneShot email preference id.
Body parameters
namestring
The name of the email preference.
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/email-preferences/[segmentation_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"name": "string"}'
Success response
{
{
"email_preference": {
"segmentation_id": 0,
"name": "string",
"display_order": 0,
"segments": [
{
"segment_id": 0,
"name": "string",
"display_order": 0
}
]
}
}
}Error response
{
"code": "122",
"message": "That record already exists"
}Events
Your StoneShot events can be managed and queried.
Get events
More
Less
GET/events
Retrieve events associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
event_idnamesummarydescriptioncreate_date_utcupdate_date_utcteams.nametags.namecustom_fields.custom_field_idcustom_fields.display_name
Other fields
typeurlsalesforce_campaign_idteams.team_idtags.tag_idcustom_fields.namecustom_fields.order_bystart_dateend_datesessions.segmentation_id
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is event_id descending.
name
Restrict results based on the event name.
tag
Restrict results based on events with a given tag.
team
Restrict results based on events with a given team.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"events": [
{
"name": "string",
"summary": "string",
"description": "string",
"create_date_utc": "2020-10-07T08:27:25Z",
"update_date_utc": "2020-10-07T08:27:25Z",
"tags": [],
"teams": [],
"custom_fields": []
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get event
More
Less
GET/events/{event_id}
Get information about a specific event in your account.
Path parameters
event_id
The unique StoneShot event id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
event_idnamesummarydescriptioncreate_date_utcupdate_date_utcteams.nametags.namecustom_fields.custom_field_idcustom_fields.display_name
Other fields
typeurlsalesforce_campaign_idteams.team_idtags.tag_idcustom_fields.namecustom_fields.order_bystart_dateend_datesessions.segmentation_id
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events/[event_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"event": {
"name": "string",
"summary": "string",
"description": "string",
"create_date_utc": "2020-06-23T16:12:18Z",
"update_date_utc": "2020-06-23T16:12:18Z",
"tags": [],
"teams": [],
"custom_fields": []
}
}Error response
{
"code": "117",
"message": "No data found"
}Get event sessions
More
Less
GET/events/{event_id}/sessions
Retrieve sessions in an event associated with your account.
Path parameters
event_id
The unique StoneShot event id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
session_idlocationdescriptionstart_datetags.namecustom_field_values.custom_field_idcustom_field_values.text_contentstatuses.namestatuses.countstatuses.segment_idvenue.venue_idvenue.namevenue.cityspeaker.speaker_idspeaker.namespeaker.locationagenda.nameagenda.timeslotmoderator.speaker_idmoderator.namemoderator.location
Other fields
end_datearrive_datesalesforce_campaign_idtags.tag_idsegmentation_id
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is session_id descending.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events/[event_id]/sessions" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"sessions": [
{
"location": "string",
"description": "string",
"start_date": "2020-10-07T08:27:25",
"custom_field_values": [],
"tags": [],
"statuses": [],
"venue": [],
"speaker": [],
"moderator": [],
"agenda": []
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get event session
More
Less
GET/events/{event_id}/sessions/{session_id}
Get information about a specific session in an event in your account.
Path parameters
event_id
The unique StoneShot event id.
session_id
The unique StoneShot session id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
session_idlocationdescriptionstart_datetags.namecustom_field_values.custom_field_idcustom_field_values.text_contentstatuses.namestatuses.countstatuses.segment_idvenue.venue_idvenue.namevenue.cityspeaker.speaker_idspeaker.namespeaker.locationagenda.nameagenda.timeslotmoderator.speaker_idmoderator.namemoderator.location
Other fields
end_datearrive_datesalesforce_campaign_idtags.tag_idsegmentation_id
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events/[event_id]/sessions/[session_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"session": {
"location": "string",
"description": "string",
"start_date": "2020-06-23T16:12:18",
"custom_field_values": [],
"tags": [],
"statuses": [],
"venue": [],
"speaker": [],
"moderator": [],
"agenda": []
}
}Error response
{
"code": "117",
"message": "No data found"
}Get event session contacts
More
Less
GET/events/{event_id}/sessions/{session_id}/contacts
Get contacts who are associated to a specific session in an event in your account.
Path parameters
event_id
The unique StoneShot event id.
session_id
The unique StoneShot session id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
emailfirst_namelast_namecompanycontact_idstatus
Other fields
unique_user_idsalesforce_idsiebel_iddynamics_idcontact_guid
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is contact_id descending.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events/[event_id]/sessions/[session_id]/contacts" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"status": "string"
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get speakers
More
Less
GET/events/speakers
Retrieve event speakers associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
speaker_idnamejob_titlelocation
Other fields
photo_urldescriptionprofile_url
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is speaker_id descending.
name
Restrict results based on the speaker name.
location
Restrict results based on a location.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events/speakers" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"speakers": [
{
"name": "string",
"job_title": "string",
"location": "string"
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get speaker
More
Less
GET/events/speakers/{speaker_id}
Get information about a specific event speaker in your account.
Path parameters
speaker_id
The unique StoneShot speaker id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
speaker_idnamejob_titlelocation
Other fields
photo_urldescriptionprofile_url
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events/speakers/[speaker_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"speaker": {
"name": "string",
"job_title": "string",
"location": "string"
}
}Error response
{
"code": "117",
"message": "No data found"
}Get venues
More
Less
GET/events/venues
Retrieve event venues associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
venue_idnameaddress_1address_2address_3address_4citycountrypostcodecapacityoverbook
Other fields
countyphoto_urlmap_urlemailtelephonecontactdescriptionlatitudelongitude
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is venue_id descending.
name
Restrict results based on the venue name.
city
Restrict results based on a city.
country
Restrict results based on a country.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events/venues" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"venues": [
{
"name": "string",
"address_1": "string",
"address_2": "string",
"address_3": "string",
"address_4": "string",
"city": "string",
"country": "string",
"postcode": "string",
"capacity": 0,
"overbook": 0
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get venue
More
Less
GET/events/venues/{venue_id}
Get information about a specific event venue in your account.
Path parameters
venue_id
The unique StoneShot venue id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
venue_idnameaddress_1address_2address_3address_4citycountrypostcodecapacityoverbook
Other fields
countyphoto_urlmap_urlemailtelephonecontactdescriptionlatitudelongitude
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/events/venues/[venue_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"venue": {
"name": "string",
"address_1": "string",
"address_2": "string",
"address_3": "string",
"address_4": "string",
"city": "string",
"country": "string",
"postcode": "string",
"capacity": 0,
"overbook": 0
}
}Error response
{
"code": "117",
"message": "No data found"
}Feeds
Your StoneShot CDS feeds can be managed and queried.
Get feed articles
More
Less
GET/feeds/{feed_id}/articles
Retrieve articles in a feed associated with your account.
Path parameters
feed_id
The unique StoneShot feed id.
Query parameters
category
Restrict results based on the category assigned.
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
article_idnamesummary_htmlbody_htmlurlimage_urlupdate_date_utcpublish_date_utccategorystatustypelanguageauthorcustom_field_values.custom_field_idcustom_field_values.text_contenttags.name
Other fields
create_date_utctimezonetags.tag_id
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is article_id descending.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/feeds/[feed_id]/articles" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"articles": [
{
"name": "string",
"summary_html": "string",
"body_html": "string",
"url": "string",
"image_url": "string",
"update_date_utc": "2018-09-27T15:27:25Z",
"publish_date_utc": "2018-09-27T15:27:25Z",
"category": "string",
"status": "string",
"type": "string",
"language": "string",
"author": "string",
"custom_field_values": [],
"tags": [],
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get feed article
More
Less
GET/feeds/{feed_id}/articles/{article_id}
Get information about a specific article in a feed in your account.
Path parameters
feed_id
The unique StoneShot feed id.
article_id
The unique StoneShot article id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
article_idnamesummary_htmlbody_htmlurlimage_urlupdate_date_utcpublish_date_utccategorystatustypelanguageauthorcustom_field_values.custom_field_idcustom_field_values.text_contenttags.name
Other fields
create_date_utctimezonetags.tag_id
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/feeds/[feed_id]/articles/[article_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"article": [
{
"name": "string",
"summary_html": "string",
"body_html": "string",
"url": "string",
"image_url": "string",
"update_date_utc": "2018-09-27T15:27:25Z",
"publish_date_utc": "2018-09-27T15:27:25Z",
"category": "string",
"status": "string",
"type": "string",
"language": "string",
"author": "string",
"custom_field_values": [],
"tags": [],
}
]
}Error response
{
"code": "117",
"message": "No data found"
}Files
Your StoneShot files can be managed and queried.
Get files
More
Less
GET/files
Retrieve files associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
file_namefolder_namefile_typesizeurlcreate_date_utcupdate_date_utc
count
The number of records to return. The default value is 1000; maximum allowed value is 5000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is update_date_utc descending.
file_name
Restrict results based on the file name. The correct folder name must also be provided when filtering by file name, unless the file is located at the root, where it can be left empty.
folder_name
Restrict results based on the name of the folder that the file is located in. If no folder name is provided, files at the root will be returned.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/files" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"files": [
{
"file_name": "string",
"folder_name": "string",
"file_type": "string",
"size": "string",
"url": "string",
"create_date_utc": "2020-10-07T08:27:25Z",
"update_date_utc": "2020-10-07T08:27:25Z"
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Upload file
More
Less
POST/files
Upload a file to your account.
Body parameters
fileFile
The file to be uploaded.
folder_pathstring
The folder path to upload your file to.
cURL example
curl -L -X POST \
"https://api.stoneshot.com/v1/files" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-F 'file=@/path/to/file'
Success response
{
"code": "100",
"message": "Success"
}Error response
{
"code": "128",
"message": "Invalid file type"
}Forms
Your StoneShot forms can be managed and queried.
Get form
More
Less
GET/forms/{smart_form_ID}
Get information for a specific form in your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
smart_form_idfriendly_form_nameUrlcreate_date_utcupdate_date_utctags.name
Other fields
tags.tag_id
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/form/smart_form_id" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"files": [
{
"smart_form_id": 0,
"friendly_form_name": "string",
"url": "string",
"create_date_utc": "2020-10-07T08:27:25Z",
"update_date_utc": "2020-10-07T08:27:25Z",
"tags": [
{
"name": "string"
}
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get forms
More
Less
GET/forms
Retrieve forms associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
smart_form_idfriendly_form_nameUrlcreate_date_utcupdate_date_utctags.name
Other fields
tags.tag_id
count
The number of records to return. The default value is 1000; maximum allowed value is 5000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is update_date_utc descending.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/forms" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"files": [
{
"smart_form_id": 0,
"friendly_form_name": "string",
"url": "string",
"create_date_utc": "2020-10-07T08:27:25Z",
"update_date_utc": "2020-10-07T08:27:25Z",
"tags": [
{
"name": "string"
}
],
}
]
}
Error response
{
"code": "117",
"message": "No data found"
}Get form submissions
More
Less
GET/forms/submissions/{smart_form_id}
Get information for a specific form submissions in your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
submission_idsubmitted_on_utccontact.emailcontact.titlecontact.first_namecontact.last_namecontact.companycontact.create_date_utccontact.contact_idcontact.last_active_utc
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/forms/submissions/smart_form_id" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"form": [
"submission_id": 0,
"submitted_on_utc": "2020-10-07T08:27:25Z",
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-10-07T08:27:25Z",
"last_active_utc": "2020-10-07T08:27:25Z"
}
]
}
Error response
{
"code": "117",
"message": "No data found"
}Lists
Your StoneShot lists, both dynamic and static can be managed and queried.
Get lists
More
Less
GET/lists
Retrieve lists associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
list_idnametypeteams.nametags.namecreate_date_utc
Other fields
external_idupdate_date_utcteams.team_idtags.tag_id
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is list_id descending.
name
Restrict results based on the list name.
tag
Restrict results based on lists with a given tag.
team
Restrict results based on lists with a given team.
type
Restrict results to ‘static’ or ‘dynamic’ lists only by including either keyword. Not including this parameter will return both static and dynamic lists.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/lists" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"lists": [
{
"name": "string",
"create_date_utc": "2020-10-07T08:27:25Z",
"tags": [],
"teams": [],
"type": "string"
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Create list
More
Less
POST/lists
Create a new static list against your account.
Body parameters
namestring
The name of your list.
tagsobject
The tags to be assigned to your list.
teamsobject
The teams to be assigned to your list.
cURL example
curl -L -X POST \
"https://api.stoneshot.com/v1/lists" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"name": "string"}'
Success response
{
"list": {
"name": "string",
"create_date_utc": "2020-10-16T12:06:34Z",
"tags": [],
"teams": [],
"type": "string"
}
}Error response
{
"code": "118",
"message": "Required parameter/s not supplied"
}Get list
More
Less
GET/lists/{list_id}
Get information for a specific list in your account.
Path parameters
list_id
The unique StoneShot list id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
list_idnametypeteams.nametags.namecreate_date_utc
Other fields
external_idupdate_date_utcteams.team_idtags.tag_id
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/lists/[list_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"list": {
"name": "string",
"create_date_utc": "2020-06-23T16:12:18Z",
"tags": [],
"teams": [],
"type": "string"
}
}Error response
{
"code": "117",
"message": "No data found"
}Get list contacts
More
Less
GET/lists/{list_id}/contacts
Get contact information for all contacts that form part of a specific list.
Path parameters
list_id
The unique StoneShot list id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
emailtitlefirst_namelast_namecompanycreate_date_utccontact_idlast_active_utc
Other fields
middle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlcreate_date_utcis_bouncesalesforce_account_idsalesforce_owner_iddouble_opt_in_statusunique_user_idsalesforce_idsiebel_iddynamics_idsegments.segment_idsegments.namesegments.segmentation.namesegments.segmentation.segmentation_idemail_preferences.segment_idemail_preferences.nameemail_preferences.segmentation.nameemail_preferences.segmentation.segmentation_idcontent_preferences.content_tag_idcontent_preferences.tag.tag_idcontent_preferences.tag.nameevents.segment_idevents.nameevents.segmentation.nameevents.segmentation.segmentation_idevents.session.session_idevents.session.locationevents.session.event.event_idevents.session.event.namedocument_preferences.segment_iddocument_preferences.namedocument_preferences.segmentation.namedocument_preferences.segmentation.segmentation_id
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guid
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guid
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is contact_id descending.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/lists/[list_id]/contacts" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2020-07-14T13:16:00Z"
},
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Add contact to list
More
Less
PATCH/lists/{list_id}/contacts/add
Add an existing contact to a specific static list.
Path parameters
list_id
The unique StoneShot list id.
Body parameters
member_url_idstring
The contact member url (optional)
salesforce_idstring
The contact salesforce id (optional).
dynamics_idstring
The contact microsoft dynamics id (optional).
siebel_idstring
The contact siebel id (optional).
unique_user_idstring
The contact unique external user id (optional).
contact_idinteger
The unique StoneShot contact id (optional).
emailstring
The contact email address (optional).
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/lists/[list_id]/contacts/add"
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string"}'
Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2017-07-27T17:34:51Z"
}
]
}Error response
{
"code": "117",
"message": "No data found"
}Remove contact from list
More
Less
PATCH/lists/{list_id}/contacts/remove
Remove a contact from a specific static list.
Path parameters
list_id
The unique StoneShot list id.
Body parameters
member_url_idstring
The contact member url (optional)
salesforce_idstring
The contact salesforce id (optional).
dynamics_idstring
The contact microsoft dynamics id (optional).
siebel_idstring
The contact siebel id (optional).
unique_user_idstring
The contact unique external user id (optional).
contact_idinteger
The unique StoneShot contact id (optional).
emailstring
The contact email address (optional).
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/lists/[list_id]/contacts/remove"
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string"}'
Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2017-07-27T17:34:51Z"
}
]
}Error response
{
"code": "117",
"message": "No data found"
}Ping
Check the StoneShot API status.
Ping request
More
Less
GET/ping
Ping the StoneShot API to return the current status.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/ping" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"code": "100",
"message": "Success"
}Segmentation
Your StoneShot segmentation, a powerful feature for segmenting contacts.
Get segmentations
More
Less
GET/segmentations
Retrieve all segmentations against your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
segmentation_idnamedisplay_ordersegments.segment_idsegments.namesegments.display_order
Other fields
dynamic_system_namesegments.detailssegments.dynamic_from_emailsegments.dynamic_from_namesegments.dynamic_fields.dynamic_field_idsegments.dynamic_fields.namesegments.dynamic_fields.display_ordersegments.dynamic_fields.html_contentsegments.dynamic_fields.text_content
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is segmentation_id descending.
name
Restrict results based on the segmentation name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/segmentations" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"segmentations": [
{
"segmentation_id": 0,
"name": "string",
"display_order": 0,
"segments": [
{
"segment_id": 0,
"name": "string",
"display_order": 0
},
{
"segment_id": 0,
"name": "string",
"display_order": 0
}
]
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get segmentation
More
Less
GET/segmentations/{segmentation_id}
Retrieve segmentation against your account.
Path parameters
segmentation_id
The unique StoneShot segmentation id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
segmentation_idnamedisplay_ordersegments.segment_idsegments.namesegments.display_order
Other fields
dynamic_system_namesegments.detailssegments.dynamic_from_emailsegments.dynamic_from_namesegments.dynamic_fields.dynamic_field_idsegments.dynamic_fields.namesegments.dynamic_fields.display_ordersegments.dynamic_fields.html_contentsegments.dynamic_fields.text_content
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/segmentations/[segmentation_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"segmentation": [
{
"segmentation_id": 0,
"name": "string",
"display_order": 0,
"segments": [
{
"segment_id": 0,
"name": "string",
"display_order": 0
},
{
"segment_id": 0,
"name": "string",
"display_order": 0
}
]
}
]
}Error response
{
"code": "117",
"message": "No data found"
}Templates
Your StoneShot templates can be managed and queried.
Get templates
More
Less
GET/templates
Retrieve templates associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
template_idnamesubjectfrom_namefrom_emailteams.nametags.namecreate_date_utc
Other fields
update_date_utcb_subjectreply_to_addressencodingteams.team_idtags.tag_id
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is template_id descending.
name
Restrict results based on the template name.
tag
Restrict results based on templates with a given tag.
team
Restrict results based on templates with a given team.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/templates" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"templates": [
{
"name": "string",
"create_date_utc": "2020-10-07T08:27:25Z",
"tags": [],
"teams": [],
"subject": "string",
"from_name": "string",
"from_email": "string"
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get template
More
Less
GET/templates/{template_id}
Get information for a specific template in your account.
Path parameters
template_id
The unique StoneShot template id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
template_idnamesubjectfrom_namefrom_emailhtml_share_linktext_share_linkteams.nametags.namecreate_date_utclist.list_idlist.namelist.typelist.create_date_utc
Other fields
update_date_utcb_subjectreply_to_addressencodingteams.team_idtags.tag_idlist.external_idlist.update_date_utc
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/templates/[template_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"template": {
"name": "string",
"html_share_link": "string",
"text_share_link": "string",
"create_date_utc": "2020-06-23T16:12:18Z",
"tags": [],
"teams": [],
"subject": "string",
"from_name": "string",
"from_email": "string",
"list": {
"list_id": 0,
"name": "string",
"create_date_utc": "2020-06-23T16:12:18Z",
"type": "string"
}
}
}Error response
{
"code": "117",
"message": "No data found"
}Users
Your StoneShot users can be managed and queried.
Get users
More
Less
GET/users
Retrieve users associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
user_idlogin_namefirst_namelast_nameemaillast_login_date_utcenabled
Other fields
external_id
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is user_id descending.
email
Restrict results based on the user’s email.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/users" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"users": [
{
"user_id": 0,
"login_name": "string",
"email": "string",
"enabled": boolean,
"last_login_date_utc": "2020-06-23T16:12:18Z",
"first_name": "string",
"last_name": "string"
}
]
}
Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get user
More
Less
GET/users/{user_id}
Get information for a specific user in your account.
Path parameters
user_id
The unique StoneShot user id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
user_idlogin_namefirst_namelast_nameemaillast_login_date_utcenabled
Other fields
external_id
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/users/[user_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"user": {
"user_id": 0,
"login_name": "string",
"email": "string",
"enabled": boolean,
"last_login_date_utc": "2020-06-23T16:12:18Z",
"first_name": "string",
"last_name": "string"
}
}Error response
{
"code": "117",
"message": "No data found"
}Update user
More
Less
PATCH/users/{user_id}
Update the details for a user in your account.
Path parameters
user_id
The unique StoneShot user id.
Body parameters
emailstring
The email address of the user.
last_namestring
The last name of the user.
enabledboolean
Whether or not the user should have access to StoneShot.
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/users/[user_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string", "last_name": "string", "enabled": boolean}'
Success response
{
"user": {
"user_id": 0,
"login_name": "string",
"email": "string",
"enabled": boolean,
"last_login_date_utc": "2020-06-23T16:12:18Z",
"first_name": "string",
"last_name": "string"
}
}Error response
{
"code": "130",
"message": "Admin/API-only users cannot be updated"
}Visit Tracking
Your StoneShot tracked sites can be managed and queried.
Get sites
More
Less
GET/sites
Retrieve tracked sites associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
site_idnamecreated_date_utcmain_url
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is site_id descending.
name
Restrict results based on the site name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/sites" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"sites": [
{
"site_id": 0,
"name": "string",
"main_url": "string",
"created_date_utc": "2020-09-15T15:19:45Z"
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get site visitors
More
Less
GET/sites/{site_id}/visitors
Retrieve details of visits to your tracked site. Visits from unknown contacts are grouped together into one child.
Path parameters
site_id
The unique StoneShot site id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
visitspage_viewstotal_bouncessite.site_idsite.namesite.created_date_utcsite.main_urlcontact.emailcontact.titlecontact.first_namecontact.last_namecontact.companycontact.create_date_utccontact.contact_idcontact.last_active_utc
Other fields
contact.middle_namecontact.websitecontact.job_titlecontact.telephonecontact.telephone_extcontact.faxcontact.mobile_numbercontact.home_numbercontact.address_1contact.address_2contact.address_3contact.address_4contact.citycontact.countycontact.postcodecontact.countrycontact.opt_incontact.custom_1contact.custom_2contact.custom_3contact.custom_4contact.custom_5contact.custom_6contact.custom_7contact.custom_8contact.custom_9contact.custom_10contact.custom_11contact.custom_12contact.prefer_htmlcontact.is_bouncecontact.salesforce_account_idcontact.salesforce_owner_idcontact.unique_user_idcontact.salesforce_idcontact.siebel_idcontact.dynamics_idcontact_guid
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is visits descending.
from_date_utc
Only retrieve visits that occurred on or after this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
to_date_utc
Only retrieve visits that occurred on or before this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/sites/[site_id]/visitors" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"visitors": {
"visits": 0,
"page_views": 0,
"total_bounces": 0,
"site": {
"site_id": 0,
"name": "string",
"main_url": "string",
"created_date_utc": "2018-12-14T22:38:26Z"
},
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2018-05-16T08:47:33Z",
"last_active_utc": "2021-01-27T16:22:08Z"
}
}
}Error response
{
"code": "117",
"message": "No data found"
}Get site visitor
More
Less
GET/sites/{site_id}/visitors/{identifier}
Retrieve details of visits to your tracked site from a specific contact.
Path parameters
site_id
The unique StoneShot site id.
identifier
A unique identifier for the contact. See contact matching for a list of the supported identifiers.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
visitspage_viewstotal_bouncessite.site_idsite.namesite.created_date_utcsite.main_urlcontact.emailcontact.titlecontact.first_namecontact.last_namecontact.companycontact.create_date_utccontact.contact_idcontact.last_active_utc
Other fields
contact.middle_namecontact.websitecontact.job_titlecontact.telephonecontact.telephone_extcontact.faxcontact.mobile_numbercontact.home_numbercontact.address_1contact.address_2contact.address_3contact.address_4contact.citycontact.countycontact.postcodecontact.countrycontact.opt_incontact.custom_1contact.custom_2contact.custom_3contact.custom_4contact.custom_5contact.custom_6contact.custom_7contact.custom_8contact.custom_9contact.custom_10contact.custom_11contact.custom_12contact.prefer_htmlcontact.is_bouncecontact.salesforce_account_idcontact.salesforce_owner_idcontact.unique_user_idcontact.salesforce_idcontact.siebel_idcontact.dynamics_idcontact_guid
from_date_utc
Only retrieve visits that occurred on or after this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
to_date_utc
Only retrieve visits that occurred on or before this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/sites/[site_id]/visitors/[identifier]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"visitor": {
"visits": 0,
"page_views": 0,
"total_bounces": 0,
"site": {
"site_id": 0,
"name": "string",
"main_url": "string",
"created_date_utc": "2018-12-14T22:38:26Z"
},
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2018-05-16T08:47:33Z",
"last_active_utc": "2021-01-27T16:22:08Z"
}
}
}Error response
{
"code": "132",
"message": "Invalid date format. Please provide dates in the following format: {yyyy-MM-ddTHH:mm:ss.fffZ}"
}Get site visit activities
More
Less
GET/sites/{site_id}/visits/activities
Retrieve visit activity details for your tracked site.
Path parameters
site_id
The unique StoneShot site id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
activity_date_utcpage_visitedlocation_ipfriendly_page_namenew_or_returningsite.site_idsite.namesite.created_date_utcsite.main_urlcontact.emailcontact.titlecontact.first_namecontact.last_namecontact.companycontact.create_date_utccontact.contact_idcontact.last_active_utccampaign.campaign_idcampaign_name
Other fields
browserreferrerscreen_resolutiondurationcontact.middle_namecontact.websitecontact.job_titlecontact.telephonecontact.telephone_extcontact.faxcontact.mobile_numbercontact.home_numbercontact.address_1contact.address_2contact.address_3contact.address_4contact.citycontact.countycontact.postcodecontact.countrycontact.opt_incontact.custom_1contact.custom_2contact.custom_3contact.custom_4contact.custom_5contact.custom_6contact.custom_7contact.custom_8contact.custom_9contact.custom_10contact.custom_11contact.custom_12contact.prefer_htmlcontact.is_bouncecontact.salesforce_account_idcontact.salesforce_owner_idcontact.unique_user_idcontact.salesforce_idcontact.siebel_idcontact.dynamics_idcontact_guid
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is activity_date_utc descending.
unknown
Boolean field (true/false) to specify whether unknown visits should be included. Default is to include known and unknown.
from_date_utc
Only retrieve visits that occurred on or after this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
to_date_utc
Only retrieve visits that occurred on or before this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/sites/[site_id]/visits/activities" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"activities": {
"activity_date_utc": "2020-01-20T11:12:31Z",
"page_visited": "string",
"location_ip": "string",
"friendly_page_name": "string",
"site": {
"site_id": 0,
"name": "string",
"main_url": "string",
"created_date_utc": "2018-12-14T22:38:26Z"
},
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2018-05-16T08:47:33Z",
"last_active_utc": "2021-01-27T16:22:08Z"
},
"campaign": {
"campaign_id": 0,
"name": "string"
},
"new_or_returning": "string"
}
}Error response
{
"code": "132",
"message": "Invalid date format. Please provide dates in the following format: {yyyy-MM-ddTHH:mm:ss.fffZ}"
}Get site visitor activities
More
Less
GET/sites/{site_id}/visits/activities/contacts/{identifier}
Retrieve details of visit activity on your tracked site by a specific contact.
Path parameters
site_id
The unique StoneShot site id.
identifier
A unique identifier for the contact. See contact matching for a list of the supported identifiers.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
emailtitlefirst_namelast_namecompanycreate_date_utccontact_idlast_active_utcvisit_activities.activity_date_utcvisit_activities.page_visitedvisit_activities.location_ipvisit_activities.friendly_page_namevisit_activities.new_or_returningvisit_activities.site.site_idvisit_activities.site.namevisit_activities.site.created_date_utcvisit_activities.site.main_urlvisit_activities.campaign.campaign_idvisit_activities.campaign_name
Other fields
middle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlis_bouncesalesforce_account_idsalesforce_owner_idunique_user_idsalesforce_idsiebel_iddynamics_idvisit_activities.browservisit_activities.referrervisit_activities.screen_resolutionvisit_activities.durationcontact_guid
from_date_utc
Only retrieve visits that occurred on or after this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
to_date_utc
Only retrieve visits that occurred on or before this date. Provide in the following format: “yyyy-MM-ddTHH:mm:ss.fffZ”.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/sites/[site_id]/visits/activities/contacts/[identifier]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"contact": {
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2018-10-29T18:03:09Z",
"last_active_utc": "2021-01-07T14:37:37Z",
"visit_activities": [
{
"activity_date_utc": "2021-01-19T17:40:59Z",
"page_visited": "string",
"location_ip": "string",
"friendly_page_name": "string",
"site": {
"site_id": 0,
"name": "string",
"main_url": "string",
"created_date_utc": "2018-12-14T22:38:26Z"
},
"campaign": {
"campaign_id": 0,
"name": "string"
},
"new_or_returning": "string"
}
]
}
}Error response
{
"code": "132",
"message": "Invalid date format. Please provide dates in the following format: {yyyy-MM-ddTHH:mm:ss.fffZ}"
}Get goals for site
More
Less
GET/sites/{site_id}/goals
Retrieve details of goals assigned to your tracked site.
Path parameters
site_id
The unique StoneShot site id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
goal_idsite_idnamematch_attributepatternpattern_typeis_case_sensitiveallow_multiplearchivedweighting_id
Other fields
site.site_idsite.namesite.main_urlsite.created_date_utc
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is activity_date_utc descending.
name
Restrict results based on the site name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/sites/{site_id}/goals" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"goals": [
{
"goal_id": 0,
"site_id": 0,
"name": "string",
"match_attribute": 0,
"pattern": "string",
"pattern_type": 0,
"is_case_sensitive": false,
"allow_multiple": false,
"archived": false,
"weighting_id": 0
},
{
"goal_id": 0,
"site_id": 0,
"name": "string",
"match_attribute": 0,
"pattern": "string",
"pattern_type": 0,
"is_case_sensitive": false,
"allow_multiple": false,
"archived": false,
"weighting_id": 0
}
]
}
Error response
{
"code": "117",
"message": "No data found"
}
Get goal for site
More
Less
GET/goals/{goal_id}
Retrieve details of a goal assigned to your tracked site.
Path parameters
goal_id
The unique StoneShot goal id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
goal_idsite_idnamematch_attributepatternpattern_typeis_case_sensitiveallow_multiplearchivedweighting_id
Other fields
site.site_idsite.namesite.main_urlsite.created_date_utc
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/goals/{goal_id}" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"goal": {
"goal_id": 0,
"site_id": 0,
"name": "string",
"match_attribute": 0,
"pattern": "string",
"pattern_type": 0,
"is_case_sensitive": false,
"allow_multiple": false,
"archived": false,
"weighting_id": 0
}
}
Error response
{
"code": "117",
"message": "No data found"
}
Get conversions for site
More
Less
GET/sites/{site_id}/conversions
Retrieve details of conversions assigned to your tracked site.
Path parameters
site_id
The unique StoneShot site id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
conversion_idsite_idvisit_idvisitor_idgoal_idvisit_action_idwhen_converted_utcurl_action_lookup_idurlvisitor_days_since_firstvisitor_returningvisitor_count_visitsreferer_keywordreferer_namereferer_typecustom_var_k1custom_var_v1custom_var_k2custom_var_v2custom_var_k3custom_var_v3custom_var_k4custom_var_v4custom_var_k5custom_var_v5contact_idactivity_detail_id
Other fields
site.site_idsite.namesite.main_urlsite.created_date_utcgoal.goal_idgoal.site_idgoal.namegoal.match_attributegoal.patterngoal.pattern_typegoal.is_case_sensitivegoal.allow_multiplegoal.archivedgoal.weighting_id
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is activity_date_utc descending.
name
Restrict results based on the site name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/sites/{site_id}/conversions" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"trackerConversions": [
{
"conversion_id": 0,
"site_id": 0,
"visit_id": 0,
"visitor_id": "string",
"goal_id": 0,
"visit_action_id": 0,
"when_converted_utc": "2021-09-17T20:58:23Z",
"url_action_lookup_id": 0,
"url": "string",
"visitor_days_since_first": 0,
"visitor_returning": false,
"visitor_count_visits": 0,
"referer_keyword": null,
"referer_name": null,
"referer_type": false,
"custom_var_k1": null,
"custom_var_v1": null,
"custom_var_k2": null,
"custom_var_v2": null,
"custom_var_k3": null,
"custom_var_v3": null,
"custom_var_k4": null,
"custom_var_v4": null,
"custom_var_k5": null,
"custom_var_v5": null,
"contact_id": null,
"activity_detail_id": null
},
{
"conversion_id": 0,
"site_id": 0,
"visit_id": 0,
"visitor_id": "string",
"goal_id": 0,
"visit_action_id": 0,
"when_converted_utc": "2021-09-17T20:58:23Z",
"url_action_lookup_id": 0,
"url": "string",
"visitor_days_since_first": 0,
"visitor_returning": false,
"visitor_count_visits": 0,
"referer_keyword": null,
"referer_name": null,
"referer_type": false,
"custom_var_k1": null,
"custom_var_v1": null,
"custom_var_k2": null,
"custom_var_v2": null,
"custom_var_k3": null,
"custom_var_v3": null,
"custom_var_k4": null,
"custom_var_v4": null,
"custom_var_k5": null,
"custom_var_v5": null,
"contact_id": null,
"activity_detail_id": null
}
]
}
Error response
{
"code": "117",
"message": "No data found"
}
Get conversions for goal
More
Less
GET/goals/{goal_id}/conversions
Retrieve details of conversions assigned to your goal.
Path parameters
goal_id
The unique StoneShot goal id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
conversion_idsite_idvisit_idvisitor_idgoal_idvisit_action_idwhen_converted_utcurl_action_lookup_idurlvisitor_days_since_firstvisitor_returningvisitor_count_visitsreferer_keywordreferer_namereferer_typecustom_var_k1custom_var_v1custom_var_k2custom_var_v2custom_var_k3custom_var_v3custom_var_k4custom_var_v4custom_var_k5custom_var_v5contact_idactivity_detail_id
Other fields
site.site_idsite.namesite.main_urlsite.created_date_utcgoal.goal_idgoal.site_idgoal.namegoal.match_attributegoal.patterngoal.pattern_typegoal.is_case_sensitivegoal.allow_multiplegoal.archivedgoal.weighting_id
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is activity_date_utc descending.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/goals/{goal_id}/conversions" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"trackerConversions": [
{
"conversion_id": 0,
"site_id": 0,
"visit_id": 0,
"visitor_id": "string",
"goal_id": 0,
"visit_action_id": 0,
"when_converted_utc": "2021-09-17T20:58:23Z",
"url_action_lookup_id": 0,
"url": "string",
"visitor_days_since_first": 0,
"visitor_returning": false,
"visitor_count_visits": 0,
"referer_keyword": null,
"referer_name": null,
"referer_type": false,
"custom_var_k1": null,
"custom_var_v1": null,
"custom_var_k2": null,
"custom_var_v2": null,
"custom_var_k3": null,
"custom_var_v3": null,
"custom_var_k4": null,
"custom_var_v4": null,
"custom_var_k5": null,
"custom_var_v5": null,
"contact_id": null,
"activity_detail_id": null
},
{
"conversion_id": 0,
"site_id": 0,
"visit_id": 0,
"visitor_id": "string",
"goal_id": 0,
"visit_action_id": 0,
"when_converted_utc": "2021-09-17T20:58:23Z",
"url_action_lookup_id": 0,
"url": "string",
"visitor_days_since_first": 0,
"visitor_returning": false,
"visitor_count_visits": 0,
"referer_keyword": null,
"referer_name": null,
"referer_type": false,
"custom_var_k1": null,
"custom_var_v1": null,
"custom_var_k2": null,
"custom_var_v2": null,
"custom_var_k3": null,
"custom_var_v3": null,
"custom_var_k4": null,
"custom_var_v4": null,
"custom_var_k5": null,
"custom_var_v5": null,
"contact_id": null,
"activity_detail_id": null
}
]
}
Error response
{
"code": "117",
"message": "No data found"
}
Workflows
Your StoneShot marketing automation workflows can be managed and queried.
Get workflows
More
Less
GET/workflows
Retrieve workflows associated with your account.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
workflow_idnamestatusdescriptioncreated_date_utcmodified_date_utclast_start_date_utclast_end_date_utc
Other fields
list_id
count
The number of records to return. The default value is 100; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is workflow_id descending.
name
Restrict results based on the workflow name.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/workflows" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"workflows": [
{
"workflow_id": 0,
"status": boolean,
"name": "string",
"description": "string",
"created_date_utc": "2020-09-15T15:19:45Z",
"modified_date_utc": "2020-09-29T11:47:56Z",
"last_start_date_utc": "2020-09-29T11:47:56Z",
"last_end_date_utc": "2020-09-29T11:47:56Z"
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Get workflow
More
Less
GET/workflows/{workflow_id}
Retrieve specific workflow associated with your account.
Path parameters
workflow_id
The unique StoneShot workflow id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
workflow_idnamestatusdescriptioncreated_date_utcmodified_date_utclast_start_date_utclast_end_date_utc
Other fields
list_id
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/workflows/[workflow_id]" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"workflow": {
"workflow_id": 0,
"status": boolean,
"name": "string",
"description": "string",
"created_date_utc": "2020-09-15T15:19:45Z",
"modified_date_utc": "2020-09-29T11:47:56Z",
"last_start_date_utc": "2020-09-29T11:47:56Z",
"last_end_date_utc": "2020-09-29T11:47:56Z"
}
}Error response
{
"code": "117",
"message": "No data found"
}Get workflow contacts
More
Less
GET/workflows/{workflow_id}/contacts
Retrieve contacts associated to a specific workflow.
Path parameters
workflow_id
The unique StoneShot workflow id.
Query parameters
select
Include this query string for every field that you would like to return, for related objects use the dot notation. If omitted, then a default set of fields are returned.
Default fields
emailtitlefirst_namelast_namecompanycreate_date_utccontact_idlast_active_utc
Other fields
middle_namewebsitejob_titletelephonetelephone_extfaxmobile_numberhome_numberaddress_1address_2address_3address_4citycountypostcodecountryopt_incustom_1custom_2custom_3custom_4custom_5custom_6custom_7custom_8custom_9custom_10custom_11custom_12prefer_htmlcreate_date_utcis_bouncesalesforce_account_idsalesforce_owner_iddouble_opt_in_statusunique_user_idsalesforce_idsiebel_iddynamics_idsegments.segment_idsegments.namesegments.segmentation.namesegments.segmentation.segmentation_idemail_preferences.segment_idemail_preferences.nameemail_preferences.segmentation.nameemail_preferences.segmentation.segmentation_idcontent_preferences.content_tag_idcontent_preferences.tag.tag_idcontent_preferences.tag.nameevents.segment_idevents.nameevents.segmentation.nameevents.segmentation.segmentation_idevents.session.session_idevents.session.locationevents.session.event.event_idevents.session.event.namedocument_preferences.segment_iddocument_preferences.namedocument_preferences.segmentation.namedocument_preferences.segmentation.segmentation_id
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guid
custom_fields.valuecustom_fields.custom_field.custom_field_idcustom_fields.custom_field.namecustom_fields.custom_field.display_namecontact_guid
count
The number of records to return. The default value is 1000; maximum allowed value is 1000.
offset
The number of records to be skipped. The default value is 0.
sort_by
The name of the field to sort by, include a ‘-‘ in front of the field name to sort by descending otherwise sorting will be ascending. The default sort field is contact_id descending.
contact_id
Restrict results based on a unique StoneShot contact id.
email
Restrict results based on contact email address.
title
Restrict results based on contact title.
first_name
Restrict results based on contact first name.
last_name
Restrict results based on contact last name.
company
Restrict results based on contact company.
job_title
Restrict results based on contact job title.
city
Restrict results based on contact city.
county
Restrict results based on contact county.
country
Restrict results based on contact country.
salesforce_id
Restrict results based on contact salesforce id.
siebel_id
Restrict results based on contact siebel id.
dynamics_id
Restrict results based on contact microsoft dynamics id.
unique_user_id
Restrict results based on contact unique external user id.
cURL example
curl -L -X GET \
"https://api.stoneshot.com/v1/workflows/[workflow_id]/contacts" \
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]"Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2019-06-13T15:00:45Z",
"last_active_utc": "2020-08-06T15:03:10Z"
}
]
}Error response
{
"code": "116",
"message": "Invalid sort_by field. Please check your input"
}Add contact to workflow
More
Less
PATCH/workflows/{workflow_id}/contacts/add
Add a contact to a specific workflow.
Path parameters
workflow_id
The unique StoneShot workflow id.
Body parameters
member_url_idstring
The contact member url (optional)
salesforce_idstring
The contact salesforce id (optional).
dynamics_idstring
The contact microsoft dynamics id (optional).
siebel_idstring
The contact siebel id (optional).
unique_user_idstring
The contact unique external user id (optional).
contact_idinteger
The unique StoneShot contact id (optional).
emailstring
The contact email address (optional).
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/workflows/[workflow_id]/contacts/add"
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string"}'
Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2017-07-27T17:34:51Z"
}
]
}Error response
{
"code": "117",
"message": "No data found"
}Remove contact from workflow
More
Less
PATCH/workflows/{workflow_id}/contacts/remove
Remove a contact from a specific workflow.
Path parameters
workflow_id
The unique StoneShot workflow id.
Body parameters
member_url_idstring
The contact member url (optional)
salesforce_idstring
The contact salesforce id (optional).
dynamics_idstring
The contact microsoft dynamics id (optional).
siebel_idstring
The contact siebel id (optional).
unique_user_idstring
The contact unique external user id (optional).
contact_idinteger
The unique StoneShot contact id (optional).
emailstring
The contact email address (optional).
cURL example
curl -L -X PATCH \
"https://api.stoneshot.com/v1/workflows/[workflow_id]/contacts/remove"
-H "Authorization: Basic [PASSWORD_BASE_64_ENCODED]" \
-H "Content-Type: application/JSON" \
-d '{"email": "string"}'
Success response
{
"contacts": [
{
"contact_id": 0,
"email": "string",
"title": "string",
"first_name": "string",
"last_name": "string",
"company": "string",
"create_date_utc": "2017-07-27T17:34:51Z"
}
]
}Error response
{
"code": "117",
"message": "No data found"
}