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=name

Query 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_utc

Body 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

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

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

Other fields

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

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

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.

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

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.

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

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

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.

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

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

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

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.

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

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

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

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

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.

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

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

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_idlast_active_utc

Other fields

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.

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 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/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",
      "last_active_utc": "2020-01-09T15:12:17Z"
    }
  ]
}

Error response

{
  "code": "116",
  "message": "Invalid sort_by field. Please check your input"
}

Create contact

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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.

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

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

Other fields

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

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.

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

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

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

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

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

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

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

Other fields

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

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

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

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

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.

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

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

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"
}

Sign up!

Sign Up

Thanks for Updating

Watch, Learn, Create and Report