Freshsuccess - Freshsuccess Account API

Freshsuccess Account API

Overview

This API provides programmatic access to the Freshsuccess Platform.

It can be accessed via:

https://API_HOST/api/v2/ENDPOINT when using basic authentication
https://API_HOST/api/v2/ENDPOINT?api_key=YOUR_API_KEY without basic authentication

Replace API_HOST as follows:

If you are located in Europe or Asia and are connecting to our European data center, your API_HOST is api-eu.freshsuccess.com.
If you are located in the US or Pacific and are connecting to our US data center, your API_HOST is api-us.freshsuccess.com.
If you are not sure, please contact support@freshsuccess.com.

Replace ENDPOINT and YOUR_API_KEY as follows:

ENDPOINT: the endpoint you wish to access, e.g., to bulk modify an account set ENDPOINT to 'accounts' https://api-us.freshsuccess.com/api/v2/accounts?api_key=YOUR_API_KEY
YOUR_API_KEY: the api key associated with your Freshsuccess account. If you do not have an api key request one from support@freshsuccess.com.

The API is structured as follows:

GET is used for retrieving data either a single item or as a list of multiple items.
POST is used for bulk insert and/or modify operations. New entries are inserted and existing entries are modified.
PUT is used to modify an existing entry.
DELETE is used to remove or de-activate a record

Authentication

Authentication is performed by API Key. The API Key may either be specified as a query parameter (e.g., ?api_key=YOUR_API_KEY) or using HTTP basic authentication. When using basic authentication, the username should be 'api' and the password should be YOUR_API_KEY.

Batching and Rate limiting

Many of the update operations require a fair amount of processing per request. As such, the API has been designed for batch upload. PLEASE batch as many updates as possible. This will significantly improve your overall throughput and puts less load on our servers. It is fine to have batch sizes in the 1000s. We do limit the max HTTP body size to about 10MB in size.
In order to reduce the system load we limit concurrent uploads (POST requests). Do not send multiple requests prior to the last request completing. If we detect concurrent uploads you will receive a HTTP 429 error.

Requests

POST and PUT parameters are passed in the body as JSON. The http header containing content type and specifying UTF-8 as the character set should be set as follows: Content-Type: application/json; charset=utf-8. All HTTP request bodies are limited to 10MB in size (limits are subject to change).
POST parameters must be placed in a "records" array within the base object. Multiple objects with the same primary key (e.g., account_id) must not occur multiple times within a single POST request; if the do exist, there is no guarantee as to the order in which the updates are applied:

{
  "records": [
    { Parameters }
  ]
}

PUT parameters must be placed in a "data" object within the base object:

{
  "data": { Parameters }
}

Parameters for GET and DELETE are passed as URL encoded query strings (e.g., /accounts?order_by=id&direction=desc&page=0). GET requests returning multiple items support pagination. Pages are indexed from 0 and page parameters are passed as URL query strings. Boolean parameters accept all data types from which they are converted to boolean according to the following logic: Apart from "0" all the integers are considered as "true", "0" is considered as "false", "true" and "false" are considered as to their corresponding values, Default value (false) will be returned in case of non-convertible value (like String).

Responses

All results are returned as JSON and contain a "status_is_ok" boolean property indicating operation success or failure (true or false respectively). If status_is_ok is false, then the batch had failed the first level of validation. If true, then the batch had passed batch level validation, however one must check the individual sub-record status to find any records that may have failed record-level validation.

GET responses contain an array of the results ("results"), a status field ("status_is_ok") and a message field on failure ("message"); the message indicates the reason for failure. If query parameters are supplied (e.g., for sorting) those parameters and their values are also returned (e.g., "order_by", and "direction" are commonly used for sorting).

Paginated responses contain a "current_page" property to support subsequent pagination requests, as well as a "max_page_size" property that specifies the maximum number of records per page. Currently, paginated responses return up to 1000 records at a time; additional records can be retrieved by supplying the "page" query parameter. If less than 1000 records are returned, it can be assumed that there are no additional pages.

{
  "max_page_size": 1000,
  "current_page": 0,
  "status_is_ok": true,
  "results": [ { RESPONSE } ]
}

POST responses contain a "failed_results" array that contains responses for records that failed. Each failed result object contains its own "message" and "record" property indicating the record that failed (indexed from 0). They also contain a "status_is_ok" field. If the "status_is_ok" is set to false, none of the batch records were inserted or updated due to a fatal error. If a non-fatal error occurs, "status_is_ok" is set to true, and the "failed_results" contains the list of records that failed (i.e., not updated or inserted).

{
  "status_is_ok": false,
  "failed_results": [ {
      "message": "'Invalid record, missing required field: account_id", 
      "record": 1
    } ]
}

POST and PUT requests will ignore records containing an "account_id" that is not found within Freshsuccess; however the "failed_results" return field will contain the list of mismatched accounts. For example:

{
  "status_is_ok": true,
  "failed_results": [ {
     "message": "Account not found",
     "record": 1
  } ]
}

To instead fail upon the detection of missing accounts, insert the '"ignore_missing_accounts" : false' property and value into a top level options object in the base request record. The example below also shows the use of the overwrite_csm_assignmets option described in the Account Bulk Update section. E.g.,

{
  "options": {
      "ignore_missing_accounts": true,
      "overwrite_csm_assignments": true
  },
  "records": [
    { 
       Parameters...
    }
  ]
}

PUT and DELETE responses contain a "status_is_ok" field indicating if the request was successful, if the request failed the "message" string property containing a human readable response string:

{
  "status_is_ok": false,
  "message": "Invalid record, missing required field: subscription_id"
}

HTTP Response Codes

200 The request was accepted at the server. Check the result property "status_is_ok" for successful request execution. A value of true indicates request was processed successfully, however for batch requests individual records may have failed while others may have succeeded. A value of false indicates a fatal error occured and no record was processed successfully. For batch updates, the "failed_results" array contains the list of failed records and a failure reason. See the Request subsection above for more details.
429 Multiple concurrent uploads were detected. This request was rejected and not processed. Resend the request. Please use batching with a large number of records rather than sending many small concurrent requests. Currently only 1 outstanding POST/PUT request at a time is supported.
500 An internal server error occured. These errors should not occur and are logged when they do occur.
504 The request timed out. The current timeout is set to 90 seconds (do not retry prior to this timeout or you will receive a 429). This is often caused by the load-balancer rebalancing. The request should be retried after a short delay. If it happens continually, let us know (at support@freshsuccess.com)

Accounts

API to retrieve, add, modify and remove accounts. Accounts are the primary first class entity. All other data is associated with an account. An account maps to a customer and is associated with users, billing, and support data. In addition to the event usage data collected by other Freshsuccess APIs, custom dimensions and custom metrics can also be attached to an account.

Retrieve all accounts

GET /accounts

Retrieve a listing of all accounts. Note: only core account properties are returned, unless specified using the include query parameter (using the include query parameter, one can fetch the list of custom value and label dimensions, as well as the list of assigned csms). To return all properties by default, including dimensions, stage history and nps history, get a single account.
Pagination is supported. Current MRR is reported in cents.

URL Parameters

Name	Type	Required	Param Type	Description
order_by	string	no	query	Field by which to order results. Choices include: account_id, name, join_date.
direction	string Default: asc	no	query	Sets the direction of sorting. Choices include: asc, desc.
page	integer	no	query	Page to view (for paginated requests)
include_inactive	boolean Default: false	no	query	Show inactive accounts
include	string	no	query	Include one or more pieces of extra information about the account. If more than one choice is provided the choices must be separated by a comma. Choices include: custom_value_dimensions, custom_label_dimensions, custom_event_dimensions, assigned_csms.

Example Response

{
  "current_page": 0, 
  "status_is_ok": true, 
  "include_inactive": true, 
  "results": [
    {
      "account_id": "12345", 
      "name": "Cocoa Ltd", 
      "crm_account_id": "crm-12345", 
      "billing_account_id": "billing-12345", 
      "support_account_id": "support-12345", 
      "billing_street": "66155 Malcom Trace Suite 234", 
      "billing_city": "Nicolleton", 
      "billing_state": "AS", 
      "billing_postal_code": "44411", 
      "billing_country": "USA", 
      "phone": "605.917.5197", 
      "employees": 4520, 
      "industry": "Food", 
      "tier": "High touch accounts", 
      "csm_score": 53, 
      "sales_rep_name": "Miss Aline Ledner", 
      "sales_rep_email": "aledner@mayert.org", 
      "source": "adwords", 
      "join_date": 1312685594018, 
      "is_active": true, 
      "current_stage": "trial", 
      "current_mrr": 0, 
      "current_nps_score": 50, 
      "current_health_score": 40
    }, 
    {
      "account_id": "45678", 
      "name": "Klein & Co", 
      "crm_account_id": "crm-45678", 
      "billing_account_id": "billing-45678", 
      "support_account_id": "support-45678", 
      "billing_street": "485 Adah Canyon Suite 933", 
      "billing_city": "Doyleville", 
      "billing_state": "FL", 
      "billing_postal_code": "35010", 
      "billing_country": "USA", 
      "phone": "929.598.1610x375", 
      "employees": 4551, 
      "industry": "B2B Saas", 
      "tier": "Medium touch accounts", 
      "csm_score": 78, 
      "sales_rep_name": "Orelia Langosh", 
      "sales_rep_email": "olangosh@mayert.org", 
      "source": "adwords", 
      "join_date": 1329830477175, 
      "is_active": false, 
      "current_stage": "established", 
      "current_mrr": 100000, 
      "current_nps_score": 75, 
      "current_health_score": 72
    }
  ]
}

Name	Type	Required Insert / Modify	Description
account_id	string(256) unique accross accounts	yes / yes	Primary account ID
name	string(512)	yes / no	Company name
join_date	long epoch milliseconds	yes / no	Earliest time company joined product; customer since
renewal_date	long epoch milliseconds	no / no	Renewal date; manually added, should only be used if renewal dates are not present in billing subscriptions, otherwise subscription renewal date will overwrite.
billing_account_id	string(256)	no / no	This account's ID in the billing system
support_account_id	string(256)	no / no	This account's ID in the support system
crm_account_id	string(256)	no / no	This account's ID in the CRM system
billing_street	string(256)	no / no	Company's street address
billing_city	string(80)	no / no	Company's city
billing_postal_code	string(80)	no / no	Company's zip or postal code
billing_state	string(80)	no / no	Company's state
billing_country	string(256)	no / no	Company's country
phone	string(80)	no / no	Primary phone number
employees	integer	no / no	Number of employees
industry	string(80)	no / no	Industry category
tier	string(80)	no / no	Current tier level
csm_score	integer 0-100	no / no	Qualitative CSM score
current_nps_score	integer -100-100	no / no	Net promoter score; directly sets the account's current NPS (rather than uploading per user NPS data).
current_mrr	integer	no / no	Current MRR in cents. NOTE: this field should NOT be set directly unless the account has NO subscription data. This field is generally computed from subscription data and will be overwritten by calculating the current MRR value from the latest subscriptions.
sales_rep_name	string(256)	no / no	Primary sale rep's name
sales_rep_email	string(256)	no / no	Primary sale rep's email
source	string(80)	no / no	Data source for account record
stage	string(80)	no / no	Current stage for account, assigns start date of current time. Only one of 'stage' or 'stage_history' should be specified at same time.
website	string(512)	no / no	Optional website of account
description	string(512)	no / no	Optional description of account
is_deleted	boolean	no / no	If true hard deletes all account data and adds the account to a deletion list that will prevent the resync of data for that account id; equivalent to state = 'deleted'. If false, it removes the account from the deletion list allowing data to be resync'ed for that account, it does not restore any previously deleted data; equivalent to state = 'active'.
is_churned	boolean	no / no	Mark account as churned if true, unchurns if false (and was inactive); when true, equivalent to state = 'churned'
inactive_time	long epoch milliseconds	no / no	Time account became inactive (deleted or churned); default, current time.
inactive_reason	string(512)	no / no	Reason account became inactive; default none
state	string(80) active,deleted,churned	no / no	Set the state of the account; equivalent to using is_deleted (see is_deleted for more details) or is_churned for setting deletion or churn; takes precedence over is_deleted/is_churned if multiple are used
parent_account_id	string(256)	no / no	Account ID of this account's parent (only for hierarchy support); explicitly set to null to remove parent link.
hierarchy_label	string(80)	no / no	Textual label of this account's position within hierarchy (only for hierarchy support)
product	string(256)	no / no	Product code for the account
region	string(256)	no / no	Region for the account
projected_churn_date	long epoch milliseconds	no / no	Projected churn date for the account (timestamp)
projected_churn_mrr	long	no / no	The Projected churn MRR in cents.
churn_likelihood	string(256) No risk,Low risk,High risk,Confirmed churn	no / no	Likelihood of churn; one of: No risk,Low risk,High risk,Confirmed churn
latest_status_title	string(80)	no / no	The account's current status; the title
latest_status_details	string(8192)	no / no	The account's current status; the details

Name	Type	Required	Param Type	Description
id	string	yes	path	Primary account ID
email	string	no	path	Rep email; delete all rep mappings for this rep.

Name	Type	Required	Param Type	Description
id	string	yes	path	Primary account ID
timestamp	long	no	path	Timestamp corresponding to NPS date

Name	Type	Required	Param Type	Description
id	string	yes	path	Primary product user ID
account_id	string	no	path	If the user ID is not globally unique, an account ID can be specified to uniquely identify user