Natero Account API

Overview

This API provides programmatic access to the Natero Customer Success 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.natero.com.
  • If you are located in the US or Pacific and are connecting to our US data center, your API_HOST is api.natero.com.
  • If you are not sure, please contact support@natero.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.natero.com/api/v2/accounts?api_key=YOUR_API_KEY
  • YOUR_API_KEY: the api key associated with your Natero account. If you do not have an api key request one from support@natero.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 deactive an entry

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 6MB 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 recieve a HTTP 429 error.

Requests

POST and PUT parameters are passed in the body as JSON with Content-Type: application/json. 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.

Responses

All results are returned as JSON and contain a "status_is_ok" boolean property indicating operation success or failure (true or false respectively).

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. 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.

{
  "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 Natero; 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. E.g.,
{
  "options": {
      "ignore_missing_accounts": 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.
  • 500 An internal server error occured. These errors should not occur and are logged when they do occur.
  • 504 The request timed out. 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@natero.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 Natero 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
NameTypeRequiredParam TypeDescription
order_bystring
noqueryField by which to order results. Choices include: account_id, name, join_date.
directionstring
Default: desc
noquerySets the direction of sorting. Choices include: asc, desc.
pageinteger
noqueryPage to view (for paginated requests)
include_inactiveboolean
Default: false
noqueryShow inactive accounts
includestring
noqueryInclude 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, 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
    }
  ]
}
 
Retrieve an account
GET /accounts/{id}
Get the listing of a single account by id. Current MRR is reported in cents.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
Example Response
{
  "status_is_ok": true, 
  "results": [
    {
      "account_id": "12345", 
      "name": "Cocoa Ltd", 
      "billing_account_id": "billing-12345", 
      "support_account_id": "support-12345", 
      "crm_account_id": "crm-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": "Medium touch accounts", 
      "csm_score": 78, 
      "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": 100000, 
      "current_nps_score": 75, 
      "current_health_score": 72, 
      "assigned_csms": [
        "joe@company.com", 
        "fred@company.com"
      ], 
      "custom_label_dimensions": {
        "favorite_chocolate_flavor": "hazelnut", 
        "favorite_fruit": "mango"
      }, 
      "custom_value_dimensions": {
        "offices_count": 20, 
        "trucks_fleet_size": 12
      }, 
      "stage_history": [
        {
          "name": "trial", 
          "start_date": 1312685594018, 
          "end_date": null
        }
      ]
    }
  ]
}
 
Bulk insert/modify accounts
POST /accounts
List of customer success managers (CSMs) to assign/unassign from this account. List is merged with any previously assigned CSMs unless the option "overwrite_csm_assignments" is set to true, see bulk insert description for more details. If an empty array is passed in with the "overwrite_csm_assignments" option set to true, then all assignments for the account are removed.
Body Parameters
NameTypeRequired
Insert / Modify
Description
account_idstring(256)
unique accross accounts
yes / yesPrimary account ID
namestring(512)
yes / noCompany name
join_datelong
epoch milliseconds
yes / noEarliest time company joined product; customer since
renewal_datelong
epoch milliseconds
no / noRenewal date; manually added, should only be used if renewal dates are not present in billing subscriptions, otherwise subscription renewal date will overwrite.
billing_account_idstring(256)
no / noThis account's ID in the billing system
support_account_idstring(256)
no / noThis account's ID in the support system
crm_account_idstring(256)
no / noThis account's ID in the CRM system
billing_streetstring(256)
no / noCompany's street address
billing_citystring(80)
no / noCompany's city
billing_postal_codestring(80)
no / noCompany's zip or postal code
billing_statestring(80)
no / noCompany's state
billing_countrystring(256)
no / noCompany's country
phonestring(80)
no / noPrimary phone number
employeesinteger
no / noNumber of employees
industrystring(80)
no / noIndustry category
tierstring(80)
no / noCurrent tier level
csm_scoreinteger
0-100
no / noQualitative CSM score
current_nps_scoreinteger
-100-100
no / noNet promoter score; directly sets the account's current NPS
sales_rep_namestring(256)
no / noPrimary sale rep's name
sales_rep_emailstring(256)
no / noPrimary sale rep's email
sourcestring(80)
no / noData source for account record
stagestring(80)
no / noCurrent stage for account, assigns start date of current time. Only one of 'stage' or 'stage_history' should be specified at same time.
websitestring(512)
no / noOptional website of account
descriptionstring(512)
no / noOptional description of account
is_deletedboolean
no / noMark account as deleted if true, undeletes if false (and was inactive)
is_churnedboolean
no / noMark account as churned if true, unchurns if false (and was inactive)
inactive_timelong
epoch milliseconds
no / noTime account became inactive (deleted or churned); default, current time.
inactive_reasonstring(512)
no / noReason account became inactive; default none
parent_account_idstring(256)
no / noAccount ID of this account's parent (only for hierarchy support)
hierarchy_labelstring(80)
no / noTextual label of this account's position within hierarchy (only for hierarchy support)
latest_status_titlestring(80)
no / noThe account's current status; the title
latest_status_detailsstring(8192)
no / noThe account's current status; the details
latest_status_datelong
epoch milliseconds
no / noThe account's current status; the date set
assigned_csmsarray
[ { email: string } ]
no / noList of customer success managers (CSMs) to assign/unassign from this account. List is merged with any previously assigned CSMs unless the option "overwrite_csm_assignments" is set to true, see bulk insert description for more details.
custom_label_dimensionsarray
[ { key: string, 
    value: string } ]
no / noArray containing one or more key/value mappings of custom label dimensions. List is merged with any previously set label dimensions.
custom_label_dimensions.keystring(256)
yes / yesName of custom label dimension
custom_label_dimensions.valuestring(256)
no / noTextual value of custom label dimension; if null will be set to null
custom_value_dimensionsarray
[ { key: string,
    value: double } ]
no / noArray containing one or more key/value mappings of custom value dimensions. List is merged with any previously set value dimensions.
custom_value_dimensions.keystring(256)
yes / yesName of custom value dimension
custom_value_dimensions.valuedouble
no / noNumeric value of custom value dimension; if null will be set to null
custom_event_dimensionsarray
[ { key: string,
    value: long } ]
no / noArray containing one or more key/value mappings of custom event dimensions. List is merged with any previously set value dimensions.
custom_event_dimensions.keystring(256)
yes / yesName of custom event dimension
custom_event_dimensions.valuelong
epoch milliseconds
no / noTimestamp value of custom event dimension; if null will be set to null
documentsarray
[ { name: string,
    url: string,
    description: string } ]
no / noArray containing one or more document urls to associate with account.
documents.namestring(80)
yes / yesDisplay name of the url
documents.urlstring(512)
yes / noActual url. E.g., https://docs.google.com/document5.pdf. If null, entry will be deleted.
documents.descriptionstring(80)
no / noOptional description
stage_historyarray
[ { name: string,
    start_date: long,
    end_date: long } ]
no / noArray containing a list of stages for an account over time. List is merged with any previously set stages (e.g., to incrementally add a new stage).
stage_history.namestring(80)
yes / no updateName of the stage
stage_history.start_datelong
epoch milliseconds
yes / no updateTimestamp of stage start time in epoch ms
stage_history.end_datelong
epoch milliseconds
yes / no updateTimestamp of stage end time in epoch ms
Omit the end_date to indicate this stage is the current stage; there can only be one current stage
nps_historyarray
[ { nps_score: long,
    date: long
    username: string } ]
no / noArray containing a list of Net promoter scores and the dates on which they occurred (optionally per user). List is merged with any previously set scores. The current score is calculated by averaging all scores in a 30 day window preceding (and including) the date of the latest score.
nps_history.nps_scorelong
yes / yesNet promoter score
nps_history.datelong
epoch milliseconds
yes / no updateTimestamp of score in epoch ms
nps_history.usernamestring(128)
no / no updateOptional username associated with score
nps_history.commentsstring(4096)
no / noOptional comments associated with score
Example Request
{
  "records": [
    {
      "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", 
      "custom_label_dimensions": [
        {
          "key": "favorite_flavor", 
          "value": "hazelnut"
        }, 
        {
          "key": "favorite_fruit", 
          "value": "mango"
        }
      ], 
      "custom_value_dimensions": [
        {
          "key": "offices_count", 
          "value": 20
        }, 
        {
          "key": "trucks_fleet_size", 
          "value": 12
        }
      ], 
      "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
    }
  ]
}
Example Request -- Assign CSMs
{
  "records": [
    {
      "account_id": "12345", 
      "assigned_csms": [
        {
          "email": "joe@company.com"
        }, 
        {
          "email": "fred@company.com"
        }
      ]
    }, 
    {
      "account_id": "6789", 
      "assigned_csms": [
        {
          "email": "joe@myco.com"
        }, 
        {
          "email": "fred@myco.com"
        }
      ]
    }
  ]
}
Example Request -- Add custom dimensions
{
  "records": [
    {
      "account_id": "12345", 
      "custom_label_dimensions": [
        {
          "key": "favorite_flavor", 
          "value": "hazelnut"
        }, 
        {
          "key": "favorite_fruit", 
          "value": "mango"
        }
      ]
    }, 
    {
      "account_id": "6789", 
      "custom_label_dimensions": [
        {
          "key": "favorite_flavor", 
          "value": "strawberry"
        }, 
        {
          "key": "favorite_fruit", 
          "value": "banana"
        }
      ]
    }
  ]
}
Example Response
{
  "status_is_ok": false, 
  "failed_results": [
    {
      "message": "'employee' value must be a number", 
      "status_is_ok": false, 
      "record": 1
    }
  ]
}
 
Modify an account
PUT /accounts/{id}
Modify a single existing account. See the POST request for the JSON body parameters.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
Example Request
{
  "data": {
    "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", 
    "custom_label_dimensions": [
      {
        "key": "favorite_flavor", 
        "value": "hazelnut"
      }, 
      {
        "key": "favorite_fruit", 
        "value": "mango"
      }
    ], 
    "custom_value_dimensions": [
      {
        "key": "offices_count", 
        "value": 20
      }, 
      {
        "key": "trucks_fleet_size", 
        "value": 12
      }
    ], 
    "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
  }
}
Example Response
{
  "status_is_ok": true
}
 
Retrieve documents
GET /accounts/{id}/documents
Returns an array of account document urls. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
pageinteger
noqueryZero indexed pagination
Example Response
{
  "current_page": 0, 
  "results": [
    {
      "account_id": "account1", 
      "description": "Description of the url contents", 
      "name": "File name 1", 
      "url": "http://test.url"
    }, 
    {
      "account_id": "account1", 
      "name": "File name 2", 
      "url": "http://test.url2"
    }
  ], 
  "status_is_ok": true
}
 
Retrieve custom metrics
GET /accounts/{id}/metrics
Returns an array of custom metrics. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
directionstring
Default: desc
noquerySets the direction of sorting (order by timestamp)
pageinteger
noqueryZero indexed pagination
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "chocolate_bars_consumption": [
        {
          "timestamp": 1312685594018, 
          "value": 3
        }, 
        {
          "timestamp": 1312623494011, 
          "value": 10
        }
      ], 
      "hazelnuts_consumption": [
        {
          "timestamp": 1312685594018, 
          "value": 145
        }, 
        {
          "timestamp": 1312623494011, 
          "value": 112
        }
      ]
    }
  ]
}
 
Retrieve invoice statements
GET /accounts/{id}/statements
Returns an array of statements for the provided account ID. All revenue is reported in cents. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
order_bystring
Default: start_date
noqueryField to order by
directionstring
Default: desc
noquerySets the direction of sorting
pageinteger
noqueryZero indexed pagination
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "account_id": "1", 
      "invoice_id": "invoice-0", 
      "non_recurring": 45493, 
      "start_date": 1410055451006, 
      "paid_date": 1411351451006, 
      "is_failed": false, 
      "line_items": [
        {
          "amount": 45493, 
          "is_recurring": false, 
          "description": "Et et provident beatae blanditiis quae recusandae rerum."
        }
      ]
    }, 
    {
      "account_id": "1", 
      "invoice_id": "invoice-1", 
      "start_date": 1411351451006, 
      "paid_date": 1412647451006, 
      "is_failed": false, 
      "recurring": 70552, 
      "non_recurring": 73196, 
      "line_items": [
        {
          "amount": 23322, 
          "is_recurring": true, 
          "description": "Consequuntur omnis ut est porro est molestias nostrum."
        }, 
        {
          "amount": 73196, 
          "is_recurring": false, 
          "description": "Dolorum et placeat similique suscipit perferendis."
        }, 
        {
          "amount": 47230, 
          "is_recurring": true, 
          "description": "Explicabo eos rerum quia et."
        }
      ]
    }
  ]
}
 
Retrieve subscription history
GET /accounts/{id}/subscriptions
Returns an array of the subscription history plan entries for the provided account ID. All revenue is reported in cents. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
order_bystring
Default: start_date
noqueryField to order by
directionstring
Default: desc
noquerySets the direction of sorting
pageinteger
noqueryZero indexed pagination
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "subscription_id": "subscription_1", 
      "account_id": "2", 
      "start_date": 1392566436543, 
      "end_date": 1395158436543, 
      "expiration_date": 1427996422070, 
      "plan_code": "plan_1", 
      "units": 18, 
      "revenue": 188595, 
      "cycle_unit": "month", 
      "cycle_length": 3
    }, 
    {
      "subscription_id": "subscription_2", 
      "account_id": "2", 
      "start_date": 1395158436543, 
      "end_date": 1397750436543, 
      "expiration_date": 1447799926555, 
      "plan_code": "plan_2", 
      "units": 91, 
      "revenue": 818019, 
      "cycle_unit": "day", 
      "cycle_length": 45
    }
  ]
}
 
Retrieve support tickets
GET /accounts/{id}/support_tickets
Returns an array of support tickets for the provided account ID. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
order_bystring
Default: create_time
noqueryField to order by
directionstring
Default: desc
noquerySets the direction of sorting
pageinteger
noqueryZero indexed pagination
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "ticket_id": "21623876183", 
      "account_id": "account_1", 
      "assignee_id": "45493", 
      "assignee_email": "Orelia.Langosh@dnb.com", 
      "type": "problem", 
      "state": "closed", 
      "priority": "normal", 
      "create_time": 1410055451006, 
      "close_time": 1411351451006, 
      "subject": "Beatae blanditiis", 
      "description": "Et et provident beatae blanditiis quae recusandae rerum."
    }, 
    {
      "ticket_id": "21623876121", 
      "account_id": "account_1", 
      "assignee_id": "45493", 
      "assignee_email": "Orelia.Langosh@dnb.com", 
      "type": "problem", 
      "state": "open", 
      "priority": "normal", 
      "create_time": 1410055451006, 
      "close_time": null, 
      "subject": "Aspernatur saepe reiciendis", 
      "description": "Deserunt non nisi at commodi."
    }
  ]
}
 
Retrieve product users
GET /accounts/{id}/users
Returns an array of users for the provided account ID. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
order_bystring
Default: user_id
noqueryField to order by
directionstring
Default: desc
noquerySets the direction of sorting
pageinteger
noqueryZero indexed pagination
include_inactiveboolean
Default: false
noqueryShow inactive/deleted account uders
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "user_id": "user_1", 
      "account_id": "account_1", 
      "first_name": "Abby", 
      "last_name": "Russel", 
      "contact_user_id": "crm_account_user_1", 
      "phone": "748-504-0993x3721", 
      "mobile_phone": "369-295-9816", 
      "email": "abby.russel@volkman.biz", 
      "salutation": "Ms.", 
      "title": "Radiographer, diagnostic", 
      "mailing_street": "924 Turcotte Creek", 
      "mailing_city": "Traceestad", 
      "mailing_state": "OR", 
      "mailing_postal_code": "77570", 
      "mailing_country": "United States of America", 
      "lead_source": "Google", 
      "product_join_date": 1397237259004, 
      "is_active": true, 
      "custom_label_dimensions": [
        {
          "key": "position", 
          "value": "Manager"
        }
      ], 
      "custom_value_dimensions": []
    }, 
    {
      "user_id": "user_2", 
      "account_id": "account_1", 
      "first_name": "Alvan", 
      "last_name": "Barton", 
      "contact_user_id": "crm_account_user_2", 
      "phone": "(517)087-7826x071", 
      "mobile_phone": "+70(6)9557740974", 
      "email": "alvan.barton@volkman.biz", 
      "salutation": "Dr.", 
      "title": "Aeronautical engineer", 
      "mailing_street": "13081 Marks Groves Apt. 603", 
      "mailing_city": "Shieldschester", 
      "mailing_state": "NJ", 
      "mailing_postal_code": "62032", 
      "mailing_country": "United States of America", 
      "lead_source": "Cold call", 
      "product_join_date": 1409079326465, 
      "is_active": true, 
      "custom_label_dimensions": [], 
      "custom_value_dimensions": []
    }
  ]
}
 
Retrieve contacts
GET /accounts/{id}/contacts
Returns an array of contacts for the provided account ID. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
order_bystring
Default: user_id
noqueryField to order by
directionstring
Default: desc
noquerySets the direction of sorting
pageinteger
noqueryZero indexed pagination
include_inactiveboolean
Default: false
noqueryShow inactive/deleted account uders
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "user_id": "user_1", 
      "account_id": "account_1", 
      "first_name": "Abby", 
      "last_name": "Russel", 
      "phone": "748-504-0993x3721", 
      "mobile_phone": "369-295-9816", 
      "email": "abby.russel@volkman.biz", 
      "salutation": "Ms.", 
      "title": "Radiographer, diagnostic", 
      "mailing_street": "924 Turcotte Creek", 
      "mailing_city": "Traceestad", 
      "mailing_state": "OR", 
      "mailing_postal_code": "77570", 
      "mailing_country": "United States of America", 
      "lead_source": "Google", 
      "is_primary": true, 
      "is_active": true, 
      "custom_label_dimensions": [
        {
          "key": "position", 
          "value": "Manager"
        }
      ], 
      "custom_value_dimensions": []
    }, 
    {
      "user_id": "user_2", 
      "account_id": "account_1", 
      "first_name": "Alvan", 
      "last_name": "Barton", 
      "phone": "(517)087-7826x071", 
      "mobile_phone": "+70(6)9557740974", 
      "email": "alvan.barton@volkman.biz", 
      "salutation": "Dr.", 
      "title": "Aeronautical engineer", 
      "mailing_street": "13081 Marks Groves Apt. 603", 
      "mailing_city": "Shieldschester", 
      "mailing_state": "NJ", 
      "mailing_postal_code": "62032", 
      "mailing_country": "United States of America", 
      "lead_source": "Cold call", 
      "is_primary": false, 
      "is_active": true, 
      "custom_label_dimensions": [], 
      "custom_value_dimensions": []
    }
  ]
}
 
Deactivate an account
DELETE /accounts/{id}
Deactivate a single account by id. By default the account is deleted, if the query parameter 'churn=true' is provided the account is marked as churned. Optionally, an inactive time can be provided; defaults to current time. If an inactive_reason is to be specified, use the accounts bulk update (POST) or single update (PUT) operation instead.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
churnstring
noqueryIf set to true, then the account is marked as churned rather than deleted
inactive_timelong
noqueryTime account became inactive (deleted or churned); default, current time.
Example Response
{
  "status_is_ok": true
}
 
Delete stage history
DELETE /accounts/{id}/stage_history/{name}/{timestamp}
Delete stages from account's stage history. Can delete all stages for an account, all stages for a name, or for a name and timestamp.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
namestring
nopathStage name; if provided deletes all stages with corresponding name from account
timestamplong
nopathTimestamp corresponding to stage start date; if provided with name; delete all entries with name, start date pair from account
 
Delete dimension values
DELETE /accounts/{id}/dimension_values/{key}
Delete dimension values from account. Can delete all dimension values for an account, or all values under a key.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
keystring
nopathDimension value key; delete all entries with key.
 
Delete dimension labels
DELETE /accounts/{id}/dimension_labels/{key}
Delete dimension labels from account. Can delete all dimension labels for an account, or all labels under a key.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
keystring
nopathDimension label key; delete all entries with key.
 
Delete assigned csm reps
DELETE /accounts/{id}/assigned_csms/{email}
Delete assigned csm reps from account. Can delete all csm reps for an account, or all mappings for a specific rep by email (email must be url encoded).
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
emailstring
nopathRep email; delete all rep mappings for this rep.
 
Delete NPS history
DELETE /accounts/{id}/nps_history/{timestamp}
Delete Net promoter scores from account's NPS history. Can delete all scores for an account, or for an account and date.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
timestamplong
nopathTimestamp corresponding to NPS date
 
Delete documents
DELETE /accounts/{id}/documents/{name}
Delete document URLs for the account. Can delete all document URLs for an account, or only an URL specified by name.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account ID
namestring
nopathName of document
 
Accounts Product Users
API to retrieve, add, modify, and remove product users. Each product account user is associated with a single account and identified by a unique product user id. Product users are users that have a login to your product. Their id must match your internal user id as used in your product (as sent in feature and module usage events). If the user is also present within your CRM, you can set the contact_user_id field.
 
Retrieve all product users
GET /account_users
Returns an array of product users. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
order_bystring
Default: user_id
noqueryField to order by
directionstring
Default: desc
noquerySets the direction of sorting
pageinteger
noqueryZero indexed pagination
include_inactiveboolean
Default: false
noqueryShow inactive/deleted account users
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "user_id": "user_1", 
      "account_id": "account_1", 
      "first_name": "Abby", 
      "last_name": "Russel", 
      "contact_user_id": "crm_account_user_1", 
      "phone": "748-504-0993x3721", 
      "mobile_phone": "369-295-9816", 
      "email": "abby.russel@volkman.biz", 
      "salutation": "Ms.", 
      "title": "Radiographer, diagnostic", 
      "mailing_street": "924 Turcotte Creek", 
      "mailing_city": "Traceestad", 
      "mailing_state": "OR", 
      "mailing_postal_code": "77570", 
      "mailing_country": "United States of America", 
      "lead_source": "Google", 
      "product_join_date": 1397237259004, 
      "is_active": true, 
      "custom_label_dimensions": [
        {
          "key": "position", 
          "value": "Manager"
        }
      ], 
      "custom_value_dimensions": []
    }, 
    {
      "user_id": "user_2", 
      "account_id": "account_2", 
      "first_name": "Alvan", 
      "last_name": "Barton", 
      "contact_user_id": "crm_account_user_2", 
      "phone": "(517)087-7826x071", 
      "mobile_phone": "+70(6)9557740974", 
      "email": "alvan.barton@volkman.biz", 
      "salutation": "Dr.", 
      "title": "Aeronautical engineer", 
      "mailing_street": "13081 Marks Groves Apt. 603", 
      "mailing_city": "Shieldschester", 
      "mailing_state": "NJ", 
      "mailing_postal_code": "62032", 
      "mailing_country": "United States of America", 
      "lead_source": "Cold call", 
      "product_join_date": 1409079326465, 
      "is_active": true, 
      "custom_label_dimensions": [], 
      "custom_value_dimensions": []
    }
  ]
}
 
Retrieve a product user
GET /account_users/{id}/{account_id}
Returns info for a single product user.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary product user ID
account_idstring
nopathIf the user ID is not globally unique, an account ID can be specified to uniquely identify user
Example Response
{
  "status_is_ok": true, 
  "results": [
    {
      "user_id": "user_1", 
      "account_id": "account_1", 
      "first_name": "Abby", 
      "last_name": "Russel", 
      "contact_user_id": "crm_account_user_1", 
      "phone": "748-504-0993x3721", 
      "mobile_phone": "369-295-9816", 
      "email": "abby.russel@volkman.biz", 
      "salutation": "Ms.", 
      "title": "Radiographer, diagnostic", 
      "mailing_street": "924 Turcotte Creek", 
      "mailing_city": "Traceestad", 
      "mailing_state": "OR", 
      "mailing_postal_code": "77570", 
      "mailing_country": "United States of America", 
      "lead_source": "Google", 
      "product_join_date": 1397237259004, 
      "is_active": true, 
      "custom_label_dimensions": [
        {
          "key": "position", 
          "value": "Manager"
        }
      ], 
      "custom_value_dimensions": []
    }
  ]
}
 
Bulk insert/modify users
POST /account_users
Insert or modify product users in bulk. Custom dimensions can be attached to users using the "dimensions" object.
Body Parameters
NameTypeRequired
Insert / Modify
Description
account_idstring(256)
yes / yesAccount ID
user_idstring(256)
yes / yesPrimary product user ID; unique across all accounts
first_namestring(80)
yes / noFirst name
last_namestring(80)
yes / noLast name
is_primaryboolean
Default: insert: false
no / noIs user primary user for this account
product_join_datelong
epoch timestamp
Default: insert: current time
yes / noJoin date of user; first time seen on product
contact_user_idstring(256)
no / noMapping from user_id to contact/crm user ID; if product user is also a contact (present in CRM)
phonestring(80)
no / noPhone number
mobile_phonestring(80)
no / noMobile phone number
emailstring(512)
no / noEmail address
salutationstring(80)
no / noGreeeting (e.g., Mr, Ms, Dr, etc)
titlestring(128)
no / noTitle of user (e.g., CEO, Customer Success Manager)
rolestring(128)
no / noRole of user (e.g., Decision Maker, Approver, Buyer)
departmentstring(128)
no / noDepartment of user
lead_sourcestring(80)
no / noSource of lead for this user
mailing_streetstring(512)
no / noStreet address
mailing_citystring(80)
no / noCity
mailing_statestring(80)
no / noState name or code
mailing_postal_codestring(80)
no / noZip/postal code
maling_countrystring(80)
no / noCountry name or code
sourcestring(80)
no / noData source of record, e.g., CRM name, etc.
is_activeboolean
Default: insert: true
no / noIs the user active; default true (active)
custom_label_dimensionsarray
[ { key: string, 
    value: string } ]
no / noArray containing one or more key/value mappings of custom label dimensions. List is merged with any previously set label dimensions.
custom_label_dimensions.keystring(256)
yes / yesName of custom label dimension
custom_label_dimensions.valuestring(256)
no / noValue of custom label dimension; if null will be set to null
custom_value_dimensionsarray
[ { key: string,
    value: double } ]
no / noArray containing one or more key/value mappings of custom value dimensions. List is merged with any previously set value dimensions.
custom_value_dimensions.keystring(256)
yes / yesName of custom value dimension
custom_value_dimensions.valuedouble
no / noValue of custom value dimension; if null will be set to null
custom_event_dimensionsarray
[ { key: string,
    value: double } ]
no / noArray containing one or more key/value mappings of custom event dimensions. List is merged with any previously set value dimensions.
custom_event_dimensions.keystring(256)
yes / yesName of custom value dimension
custom_event_dimensions.valuelong
epoch timestamp
no / noValue of custom event dimension; timestamp in epoch ms; if null will be set to null
Example Request
{
  "records": [
    {
      "user_id": "user_1", 
      "account_id": "account_1", 
      "first_name": "Abby", 
      "last_name": "Russel", 
      "product_join_date": 1438210591739, 
      "contact_user_id": "crm_account_user_1", 
      "phone": "748-504-0993x3721", 
      "mobile_phone": "369-295-9816", 
      "email": "abby.russel@volkman.biz", 
      "salutation": "Ms.", 
      "title": "Radiographer, diagnostic", 
      "mailing_street": "924 Turcotte Creek", 
      "mailing_city": "Traceestad", 
      "mailing_state": "OR", 
      "mailing_postal_code": "77570", 
      "mailing_country": "United States of America", 
      "custom_label_dimensions": [
        {
          "key": "name", 
          "value": "Manager"
        }, 
        {
          "key": "name", 
          "value": "Power User"
        }
      ], 
      "custom_value_dimensions": [
        {
          "key": "reports", 
          "value": 11.0
        }
      ]
    }
  ]
}
Example Response
{
  "status_is_ok": false, 
  "failed_results": [
    {
      "message": "Missing required field for insert: 'first_name'", 
      "status_is_ok": false, 
      "record": 1
    }
  ]
}
 
Modify a product user
PUT /account_users/{id}
Modify an existing product user. See the POST request for JSON body parameters. The body should contain the user's account_id.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary product user ID
Example Request
{
  "data": {
    "user_id": "user_1", 
    "account_id": "account_1", 
    "first_name": "Abby", 
    "last_name": "Russel", 
    "contact_user_id": "crm_account_user_1", 
    "phone": "748-504-0993x3721", 
    "mobile_phone": "369-295-9816", 
    "email": "abby.russel@volkman.biz", 
    "salutation": "Ms.", 
    "title": "Radiographer, diagnostic", 
    "lead_source": "web", 
    "mailing_street": "924 Turcotte Creek", 
    "mailing_city": "Traceestad", 
    "mailing_state": "OR", 
    "mailing_postal_code": "77570", 
    "mailing_country": "United States of America", 
    "product_join_date": 1397237259004, 
    "custom_label_dimensions": [
      {
        "key": "position", 
        "value": "Manager"
      }
    ], 
    "custom_value_dimensions": [
      {
        "key": "reports", 
        "value": 11.0
      }
    ]
  }
}
Example Response
{
  "status_is_ok": true
}
 
Deactivate a product user
DELETE /account_users/{id}/{account_id}
Delete an account user. The account user is specified via the id parameter in the path. In some cases the id may only be unique within an account (not across accounts), in this case the account_id can be specified as well.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathAccount product user ID
account_idstring
nopathAccount ID
dimensionstring
noqueryDelete specified dimension; key must be provided (must not be specified along with all_dimensions)
all_dimensionsstring
noqueryDelete all dimensions (must not be specified along with dimension)
Example Response
{
  "status_is_ok": true
}
 
Account Contacts
API to retrieve, add, modify, and remove CRM contacts. Each contact is associated with a single account and identified by a unique crm user id. Their id must match your internal crm user id as used by your CRM (if your CRM is synced to Natero).
 
Retrieve all contacts
GET /account_contacts
Returns an array of account contacts. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
order_bystring
Default: user_id
noqueryField to order by
directionstring
Default: desc
noquerySets the direction of sorting
pageinteger
noqueryZero indexed pagination
include_inactiveboolean
Default: false
noqueryShow inactive/deleted account users
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "user_id": "crm_account_user_1", 
      "account_id": "account_1", 
      "first_name": "Abby", 
      "last_name": "Russel", 
      "is_primary": true, 
      "phone": "748-504-0993x3721", 
      "mobile_phone": "369-295-9816", 
      "email": "abby.russel@volkman.biz", 
      "salutation": "Ms.", 
      "title": "Radiographer, diagnostic", 
      "mailing_street": "924 Turcotte Creek", 
      "mailing_city": "Traceestad", 
      "mailing_state": "OR", 
      "mailing_postal_code": "77570", 
      "mailing_country": "United States of America", 
      "lead_source": "Google", 
      "is_active": true, 
      "custom_label_dimensions": [
        {
          "key": "position", 
          "value": "Manager"
        }
      ], 
      "custom_value_dimensions": []
    }, 
    {
      "user_id": "crm_account_user_2", 
      "account_id": "account_2", 
      "first_name": "Alvan", 
      "last_name": "Barton", 
      "is_primary": false, 
      "phone": "(517)087-7826x071", 
      "mobile_phone": "+70(6)9557740974", 
      "email": "alvan.barton@volkman.biz", 
      "salutation": "Dr.", 
      "title": "Aeronautical engineer", 
      "mailing_street": "13081 Marks Groves Apt. 603", 
      "mailing_city": "Shieldschester", 
      "mailing_state": "NJ", 
      "mailing_postal_code": "62032", 
      "mailing_country": "United States of America", 
      "lead_source": "Cold call", 
      "is_active": true, 
      "custom_value_dimensions": [], 
      "custom_label_dimensions": []
    }
  ]
}
 
Retrieve a contact
GET /account_contacts/{id}/{account_id}
Returns info for a single contact user.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary crm user ID
account_idstring
nopathIf the user ID is not globally unique, an account ID can be specified to uniquely identify user
Example Response
{
  "status_is_ok": true, 
  "results": [
    {
      "user_id": "crm_account_user_1", 
      "account_id": "account_1", 
      "first_name": "Abby", 
      "last_name": "Russel", 
      "is_primary": true, 
      "phone": "748-504-0993x3721", 
      "mobile_phone": "369-295-9816", 
      "email": "abby.russel@volkman.biz", 
      "salutation": "Ms.", 
      "title": "Radiographer, diagnostic", 
      "mailing_street": "924 Turcotte Creek", 
      "mailing_city": "Traceestad", 
      "mailing_state": "OR", 
      "mailing_postal_code": "77570", 
      "mailing_country": "United States of America", 
      "lead_source": "Google", 
      "is_active": true, 
      "custom_label_dimensions": [
        {
          "key": "position", 
          "value": "manager"
        }
      ], 
      "custom_value_dimensions": []
    }
  ]
}
 
Bulk insert/modify contacts
POST /account_contacts
Insert or modify account contacts in bulk. Custom dimensions can be attached to contacts using the "dimensions" object.
Body Parameters
NameTypeRequired
Insert / Modify
Description
account_idstring(256)
yes / yesAccount ID
user_idstring(256)
yes / yesCRM ID of contact (or contact's id if no CRM in use)
first_namestring(80)
yes / noFirst name
last_namestring(80)
yes / noLast name
is_primaryboolean
Default: insert: false
no / noIs user primary contact for this account
phonestring(80)
no / noPhone number
mobile_phonestring(80)
no / noMobile phone number
emailstring(512)
no / noEmail address
salutationstring(80)
no / noGreeeting (e.g., Mr, Ms, Dr, etc)
titlestring(128)
no / noTitle of user (e.g., CEO, Customer Success Manager)
rolestring(128)
no / noRole of user (e.g., Decision Maker, Approver, Buyer)
departmentstring(128)
no / noDepartment of user
lead_sourcestring(80)
no / noSource of lead for this user
mailing_streetstring(512)
no / noStreet address
mailing_citystring(80)
no / noCity
mailing_statestring(80)
no / noState name or code
mailing_postal_codestring(80)
no / noZip/postal code
maling_countrystring(80)
no / noCountry name or code
sourcestring(80)
no / noData source of record, e.g., CRM name, etc.
is_activeboolean
Default: insert: true
no / noIs the user active; default true (active)
custom_label_dimensionsarray
[ { key: string, 
    value: string } ]
no / noArray containing one or more key/value mappings of custom label dimensions. List is merged with any previously set label dimensions.
custom_label_dimensions.keystring(256)
yes / yesName of custom label dimension
custom_label_dimensions.valuestring(256)
yes / yesValue of custom label dimension
custom_value_dimensionsarray
[ { key: string,
    value: double } ]
no / noArray containing one or more key/value mappings of custom value dimensions. List is merged with any previously set value dimensions.
custom_value_dimensions.keystring(256)
yes / yesName of custom value dimension
custom_value_dimensions.valuedouble
yes / yesValue of custom value dimension
custom_event_dimensionsarray
[ { key: string,
    value: double } ]
no / noArray containing one or more key/value mappings of custom event dimensions. List is merged with any previously set value dimensions.
custom_event_dimensions.keystring(256)
yes / yesName of custom value dimension
custom_event_dimensions.valuelong
epoch timestamp
yes / yesValue of custom event dimension; timestamp in epoch ms
Example Request
{
  "records": [
    {
      "user_id": "crm_account_user_1", 
      "account_id": "account_1", 
      "first_name": "Abby", 
      "last_name": "Russel", 
      "is_primary": true, 
      "phone": "748-504-0993x3721", 
      "mobile_phone": "369-295-9816", 
      "email": "abby.russel@volkman.biz", 
      "salutation": "Ms.", 
      "title": "Radiographer, diagnostic", 
      "mailing_street": "924 Turcotte Creek", 
      "mailing_city": "Traceestad", 
      "mailing_state": "OR", 
      "mailing_postal_code": "77570", 
      "mailing_country": "United States of America", 
      "custom_label_dimensions": [
        {
          "key": "position", 
          "value": "Manager"
        }
      ], 
      "custom_value_dimensions": [
        {
          "key": "reports", 
          "value": 11.0
        }
      ]
    }
  ]
}
Example Response
{
  "status_is_ok": false, 
  "failed_results": [
    {
      "message": "'is_primary' must be boolean", 
      "status_is_ok": false, 
      "record": 1
    }
  ]
}
 
Modify a contact
PUT /account_contacts/{id}
Modify an existing account contact. See the POST request for JSON body parameters.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathPrimary account contact ID
Example Request
{
  "data": {
    "user_id": "crm_account_user_1", 
    "account_id": "account_1", 
    "first_name": "Abby", 
    "last_name": "Russel", 
    "is_primary": true, 
    "phone": "748-504-0993x3721", 
    "mobile_phone": "369-295-9816", 
    "email": "abby.russel@volkman.biz", 
    "salutation": "Ms.", 
    "title": "Radiographer, diagnostic", 
    "lead_source": "web", 
    "mailing_street": "924 Turcotte Creek", 
    "mailing_city": "Traceestad", 
    "mailing_state": "OR", 
    "mailing_postal_code": "77570", 
    "mailing_country": "United States of America", 
    "custom_label_dimensions": [
      {
        "key": "position", 
        "value": "Manager"
      }
    ], 
    "custom_value_dimensions": [
      {
        "key": "reports", 
        "value": 11.0
      }
    ]
  }
}
Example Response
{
  "status_is_ok": true
}
 
Deactivate a contact
DELETE /account_contacts/{id}/{account_id}
Delete an account contact. The account user is specified via the id parameter in the path. In some cases the id may only be unique within an account (not across accounts), in this case the account_id can be specified as well.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathAccount crm user ID
account_idstring
nopathIf the user ID is not globally unique, an account ID can be specified to uniquely identify user
dimensionstring
noqueryDelete specified dimension; key must be provided (must not be specified along with all_dimensions)
all_dimensionsstring
noqueryDelete all dimensions (must not be specified along with dimension)
Example Response
{
  "status_is_ok": true
}
 
Custom Metrics
API to retrieve, add, modify and remove custom account metrics. Custom account metrics are identified by a unique name and contain a list of timestamp and value pairs.
 
Retrieve a metric by name
GET /metrics/{name}
Returns list of metric data points for all accounts by an individual metric
URL Parameters
NameTypeRequiredParam TypeDescription
namestring
yespathMetric name
directionstring
Default: desc
noquerySets the direction of sorting by timestamp value
pageinteger
noqueryZero indexed pagination
account_idstring
noqueryFilter by product account ID
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "account_id": "2", 
      "chocolate_bars_consumption": [
        {
          "timestamp": 1312685594018, 
          "value": 3
        }, 
        {
          "timestamp": 1312623494011, 
          "value": 10
        }
      ]
    }, 
    {
      "account_id": "5", 
      "chocolate_bars_consumption": [
        {
          "timestamp": 1312685594018, 
          "value": 7
        }, 
        {
          "timestamp": 1312623494011, 
          "value": 22
        }
      ]
    }
  ]
}
 
Bulk insert/modify metrics
POST /metrics
Insert or modify custom metrics in bulk.
Body Parameters
NameTypeRequired
Insert / Modify
Description
account_idstring(256)
yes / yesAccount ID
namestring(128)
yes / yesMetric name
metricsarray
[ { timestamp: long,
    value: double } ]
yes / yesArray of objects containing timestamps and their associated values.
metrics.timestamplong
epoch milliseconds
yes / yesTimestamp of metric
metrics.valuedouble
yes / yesValue of metric.
Example Request
{
  "records": [
    {
      "name": "chocolate_bars_consumption", 
      "account_id": "2", 
      "metrics": [
        {
          "timestamp": 1312685594018, 
          "value": 3
        }, 
        {
          "timestamp": 1312623494011, 
          "value": 10
        }
      ]
    }, 
    {
      "name": "hazelnut_consumption", 
      "account_id": "5", 
      "metrics": [
        {
          "timestamp": 1312685594018, 
          "value": 7
        }, 
        {
          "timestamp": 1312623494011, 
          "value": 22
        }
      ]
    }
  ]
}
Example Response
{
  "status_is_ok": true, 
  "failed_results": []
}
 
Modify a metric
PUT /metrics/{name}
Modify/add metric values for an existing metric name. See the POST request for JSON body parameters.
URL Parameters
NameTypeRequiredParam TypeDescription
namestring
yespathMetric name
Example Request
{
  "data": {
    "name": "chocolate_bars_consumption", 
    "account_id": "2", 
    "metrics": [
      {
        "timestamp": 1312685594018, 
        "value": 3
      }, 
      {
        "timestamp": 1312623494011, 
        "value": 10
      }
    ]
  }
}
Example Response
{
  "status_is_ok": true
}
 
Delete a metric
DELETE /metrics/{name}
Delete a custom metric
URL Parameters
NameTypeRequiredParam TypeDescription
namestring
yespathMetric name
account_idstring
noqueryFilter by product account ID; delete only those matching filter
Example Response
{
  "status_is_ok": true
}
 
Subscriptions
API to retrieve, add, modify and remove subscription plan entries. Subscriptions identify the plan an account is on. An account's subscription plan may change over time. As the subscription plan changes, this API can be used to update the accounts current subscription. The monthly recurring revenue (MRR) for each account is calculated based on the sum of MRR derived from each of the account's current subscription. Specifically, MRR is calculated by taking the total_revenue and dividing it by the number of months represented by the cycle_length * the cycle_unit (as specified in the subscription insert/update record). Renewal events are also extracted from the subscription history. All revenue is reported in cents and must be provided in cents.
 
Retrieve subscriptions
GET /subscriptions
Returns the current state of all subscription plan entries. All revenue is reported in cents. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
order_bystring
Default: start_date
noqueryField to order by
directionstring
Default: desc
noquerySets the direction of sorting
pageinteger
noqueryZero indexed pagination
Example Response
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
    {
      "subscription_id": "subscription_1", 
      "account_id": "1", 
      "records": [
        {
          "start_date": 1392566436543, 
          "end_date": null, 
          "is_end": false, 
          "is_renewal": false, 
          "expiration_date": 1437996422070, 
          "plan_code": "plan_1", 
          "total_revenue": 188595, 
          "cycle_unit": "month", 
          "cycle_length": 3
        }
      ]
    }, 
    {
      "subscription_id": "subscription_2", 
      "account_id": "2", 
      "records": [
        {
          "start_date": 1395158436543, 
          "end_date": 1397750436543, 
          "is_end": true, 
          "is_renewal": false, 
          "expiration_date": null, 
          "plan_code": "plan_2", 
          "revenue": 818019, 
          "cycle_unit": "day", 
          "cycle_length": 45
        }
      ]
    }
  ]
}
 
Retrieve a subscription
GET /subscriptions/{id}
Returns an individual subscription. All revenue is reported in cents. By default only the current state of the subscription is returned. If the query parameter 'history' is set to 'true', then the full history of the subscription is returned. To see the history for a specific account, see the GET /accounts/{id}/subscription api.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathSubscription ID
historyboolean
Default: false
noqueryIf true, the full history of the subscription is returned
Example Response
{
  "status_is_ok": true, 
  "results": [
    {
      "subscription_id": "subscription_2", 
      "account_id": "2", 
      "records": [
        {
          "start_date": 1395158436543, 
          "end_date": null, 
          "is_end": false, 
          "is_renewal": true, 
          "expiration_date": 1447799926555, 
          "plan_code": "plan_2", 
          "total_revenue": 818019, 
          "cycle_unit": "day", 
          "cycle_length": 45
        }
      ]
    }
  ]
}
 
Bulk insert/modify subscriptions
POST /subscriptions
Insert or modify subscription plan entries in bulk. The subscription plans are used to calculate monthly recurring revenue (MRR) as well as renewals and renewal rates. MRR is classified as either new (if no revenue for account has been seen before), expansion (if total MRR increases), contraction (if total MRR decreases), churn (if a subscription ends or decreases to zero revenue). All revenue must be entered in cents and is reported in cents.

Subscriptions may go through changes over their lifetimes (e.g., the price of a subscription may change over time, or a subscription may be renewed, etc). The subscription API is event based. Each record indicates that the subscription has changed in some way and alters the history of that subscription.

The API supports four types of events: 'revenue', 'renewal', 'end' and 'current' events. A 'revenue' event indicates that a change of revenue has occured (or a new subscription has started). A 'renewal' event indicates that a renewal has occured. A change of revenue may accompany the renewal (but need not be otherwise specified). An 'end' event indicates that the subscription has ended. A 'current' event, is for situations where the changes in subscription are unknown to the caller. Instead, the caller provides a snapshot of the current state of the subscription and Natero will identify the differences from the previous state of the subscription and apply them accordingly. Details on constructing 'current' events are given below.

In addition to the event type, each record contains an effective date range. The changes described in the record are applied to this time range, overriding any existing history that previously existed within this time range. The date range may be open-ended (if the 'effective_end_date' is omitted, or closed, if it is provided); however, if the 'end' event is specified, only an 'effective_start_date' is necessary (the end date is ignored).

Upcoming renewals are tracked via the 'next_renewal_date' field which indicates the starting date of the next renewal; the 'next_renewal_date' may be specified on any record. An 'event' of type 'renewal' indicates that a renewal has occured at the 'effective_start_date'. If the 'previous_renewal_date' is specified within the renewal record, the renewal event is associated with the renewal at that time period (the 'previous_renewal_date' must match a prior 'next_renewal_date' field). Otherwise, the renewal is associated with the earliest 'next_renewal_date' that has not yet been associated with a renewal.

As mentioned above, because 'current' events are a snapshot of the current state of the subscription, the date parameters have different uses from the other event types. The 'effective_start_date' is the absolute start date of this subscription. Similarly, the 'effective_end_date' is also the absolute end date of this subscription. If an 'effective_end_date' is provided, Natero will assume that the subscription has ended at the provided date. Finally, because Natero will automatically notice changes in 'next_renewal_date', you never specify 'previous_renewal_date'. The renewal will always be applied to the prior renewal date. All changes in the subscription provided through 'current' events will be applied as of the start of the current day. As such, if you want to make historical changes to the subscription, you must do so using the other event types.
Body Parameters
NameTypeRequired
Insert / Modify
Description
account_idstring(256)
yes / yesAccount ID
subscription_idstring(128)
yes / yesSubscription ID; unique across all account subscriptions for given time range. Same subscription ID may be used for non-overlapping start/end dates to indicate a renewal/extension of an existing subscription.
effective_start_datelong
epoch milliseconds
yes / yesDate at which subscription changes became effective; inclusive of end date.
To specify a time range over which this change is effective, specify both the change start and change end dates; the range is defined by: start_date >= range < end_date.
All existing events that occur during this timeframe will be overwritten.
Note that in the case of 'current' events, this should be the date at which the subscription was actually started.
effective_end_datelong
epoch milliseconds
no / noDate at which subscription changes are no longer effective; exclusive of end date (useful for changing subscription history).
If omitted, change is assumed to still be in effect and all pre-existing records ending after the 'effective_start_date' will be ended or removed depending on their start date.
Note that in the case of 'current' events, this should be date at which the subscription was actually ended and should not be provided if the subscription has not ended.
eventstring(80)
Choices: end, renewal, revenue, current
yes / yesEvent that occured at the effective start date: end - plan ended; renewal - plan renewed; revenue - revenue changed (or start of new subscription); current - record reflects current state of the subscription (see description above).
On an 'end' event only the 'effective_start_date' should be specified indicating the time at which the end event occured. The 'effective_end_date', 'total_revenue', 'cycle_unit', and 'cycle_length' are ignored if specified.
total_revenuelong
required if event not 'end'
yes / yesTotal revenue for plan over period represented by 'cycle unit' and 'cycle length'. It must include precalculated addons, discounts, etc. In cents. MRR is calculated by dividing total_revenue by the number of months represented by (cycle_unit * cycle_length).
cycle_unitstring(80)
required if event not 'end'
Choices: day, month, year
yes / yesThe amount of time per cycle unit: day, month, year. Used to convert total revenue to monthly revenue.
cycle_lengthinteger
required if event not 'end'
yes / yesThe number of cycle units for this plan
next_renewal_datelong
epoch milliseconds
no / noStart date of next renewal. May be specified with either 'renewal', 'revenue' or 'current' events.
previous_renewal_datelong
epoch milliseconds
no / noStart date of previous renewal. Should only be specified on renewal events (event == 'renewal'. It must match a prior 'next_renewal_date' or it will be ignored.
If not set, the system will apply the renewal event to earliest 'next_renewal_date' that has not yet been renewed.
plan_codestring(128)
no / noShort name/id of plan
sourcestring(80)
no / noData source for subscription record
custom_dimensionsarray
[ { key: string, 
    value: string } ]
no / noArray containing one or more key/value mappings of custom subscription dimensions. List is merged with any previously set subscription dimensions.
custom_dimensionsstring(256)
yes / yesName of custom subscription dimension
custom_dimensionsstring(256)
no / noTextual value of custom subscription dimension; if null will be set to null
 
Modify a subscription
PUT /subscriptions/{id}
Modify an existing subscription. See the POST request for JSON body parameters.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathSubscription ID
Example Request
{
  "data": {
    "subscription_id": "subscription_2", 
    "account_id": "2", 
    "effective_start_date": 1395158436543, 
    "end_date": 1397750436543
  }
}
Example Response
{
  "status_is_ok": true
}
 
Delete a subscription
DELETE /subscriptions/{id}
Delete a subscription by ID. Optionally limit deletion to specific start date (?start_date=timestamp).
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathSubscription ID to delete.
start_datelong
noqueryOptional, exact start date of the entry to delete.
Example Response
{
  "status_is_ok": false, 
  "message": "Invalid required field: subscription_id"
}
 
Invoice Statements
API to retrieve, add, modify, and remove invoice statements associated with accounts. Similar to subscriptions, a history of invoices is maintained. All revenue must be reported in cents and is retrieved in cents.
 
Retrieve an invoice
GET /statements/{id}
Returns info for an individual invoice statement. All revenue is reported in cents. Pagination is supported.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathInvoice ID
Example Response
{
  "status_is_ok": true, 
  "results": [
    {
      "account_id": "1", 
      "invoice_id": "invoice-1", 
      "start_date": 1411351451006, 
      "paid_date": 1412647451006, 
      "is_failed": false, 
      "recurring": 70552, 
      "non_recurring": 73196, 
      "line_items": [
        {
          "amount": 23322, 
          "is_recurring": true, 
          "description": "Consequuntur omnis ut est porro est molestias nostrum."
        }, 
        {
          "amount": 73196, 
          "is_recurring": false, 
          "description": "Dolorum et placeat similique suscipit perferendis."
        }, 
        {
          "amount": 47230, 
          "is_recurring": true, 
          "description": "Explicabo eos rerum quia et."
        }
      ]
    }
  ]
}
 
Bulk insert/modify invoices
POST /statements
Insert/modify invoice statements in bulk.


Invoices can contain two sub-elements: line items and transactions. Line items record details about the invoice. Transactions are used to record split-payments. Invoices may contain both recurring and/or non-recurring revenue. If not set in the base invoice, and if line items are present, then the invoice's recurring/non-recurring revenue amounts are set by summing up the relevant field within the line items. An invoice may or may not have been paid. If a paid date is set, the paid amount is calculated as the sum of the recurring and non-recurring revenue; however, if any transactions exist for the invoice, then the paid amount is set to the sum of the transactions.


A split payment has the same invoice ID, start date, and recurring/non-recurring revenue amounts, but have different transaction IDs and may have different paid dates and paid amounts. If an invoice is paid in full, there is no need to add transactions; just set the paid date to the date of payment. If transactions are present, they will override the base invoice's paid amount.


All existing line items related to an invoice are replaced whenever an invoice update contains any line items. Existing line items, based on matching account_id and invoice_id, are replaced with the line items present in the update. If no line items are present, then no changes are made to the line items.


Unlike line item updates, transactions are not replaced wholesale (since they may occur at different points in time). If a transaction is present within an invoice update, then it will replace any transaction with matching account_id, invoice_id, tx_id fields.

Body Parameters
NameTypeRequired
Insert / Modify
Description
account_idstring(256)
yes / yesAccount ID
invoice_idstring(128)
yes / yesInvoice ID; unique across invoices of all accounts
start_datelong
epoch milliseconds
yes / noTime at which the charges were created
paid_datelong
epoch milliseconds
no / noTime at which invoice was paid; if transactions are present, this field is set to null
due_datelong
epoch milliseconds
no / noTime at which invoice is due
is_failedboolean
Default: insert: false
no / noTrue if revenue collection was unsuccessful
recurringlong
no / noTotal recurring revenue for this invoice. If not provided, the sum of all recurring line items is used instead. If paid date is non-null, and no transactions are present, then the recurring and non-recurring revenue fields are summed as the payment amount.
non_recurringlong
no / noTotal non-recurring revenue for this invoice. If not provided, the sum of all non-recurring line items is used. If paid date is non-null, and no transactions are present, then the recurring and non-recurring revenue fields are summed as the payment amount.
transactionsarray
{ tx_id: string,
  paid_amount: long,
  paid_date: long }
no / noList of payment transactions.
Can be used to support split payments -- where payments of different amounts occur on different dates.
transactions.tx_idstring(128)
yes / yesTransaction id; identifies the split payment
transactions.paid_amountlong
yes / yesTotal payment for this invoice transaction in cents
transactions.paid_datelong
yes / yesPayment date for this transaction
line_itemsarray
{ amount: long,
  is_recurring: boolean,
  description: string }
no / noList of invoice line items.
If any line items are present in record, ALL old line items are removed and the new line items are inserted. To preserve old line item entries, they must be reinserted with every update.
If no line items are present in record, no existing line items are altered or deleted.
line_items.amountlong
yes / yesAmount of line item in cents
line_items.is_recurringboolean
yes / yesIs this line item recurring
line_items.descriptionstring(4096)
no / noDescription of the line item
sourcestring(80)
no / noData source for invoice statement record
Example Request
{
  "records": [
    {
      "account_id": "1", 
      "invoice_id": "invoice-0", 
      "non_recurring": 45493, 
      "start_date": 1410055451006, 
      "paid_date": 1411351451006, 
      "is_failed": false, 
      "line_items": [
        {
          "amount": 45493, 
          "is_recurring": false, 
          "description": "Et et provident beatae blanditiis quae recusandae rerum."
        }
      ]
    }, 
    {
      "account_id": "1", 
      "invoice_id": "invoice-1", 
      "start_date": 1411351451006, 
      "paid_date": 1412647451006, 
      "is_failed": false, 
      "recurring": 70552, 
      "non_recurring": 73196, 
      "line_items": [
        {
          "amount": 23322, 
          "is_recurring": true, 
          "description": "Consequuntur omnis ut est porro est molestias nostrum."
        }, 
        {
          "amount": 73196, 
          "is_recurring": false, 
          "description": "Dolorum et placeat similique suscipit perferendis."
        }, 
        {
          "amount": 47230, 
          "is_recurring": true, 
          "description": "Explicabo eos rerum quia et."
        }
      ]
    }
  ]
}
Example Response
{
  "status_is_ok": false, 
  "failed_results": [
    {
      "message": "'is_failed' value must be a boolean", 
      "status_is_ok": false, 
      "record": 2
    }
  ]
}
 
Modify an invoice
PUT /statements/{id}
Modify an existing invoice statement. See the POST request for JSON body parameters.
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathInvoice ID
Example Request
{
  "data": {
    "account_id": "1", 
    "invoice_id": "invoice-1", 
    "start_date": 1411351451006, 
    "paid_date": 1412647451006, 
    "is_failed": false, 
    "recurring": 70552, 
    "non_recurring": 73196, 
    "line_items": [
      {
        "amount": 23322, 
        "is_recurring": true, 
        "description": "Consequuntur omnis ut est porro est molestias nostrum."
      }, 
      {
        "amount": 73196, 
        "is_recurring": false, 
        "description": "Dolorum et placeat similique suscipit perferendis."
      }, 
      {
        "amount": 47230, 
        "is_recurring": true, 
        "description": "Explicabo eos rerum quia et."
      }
    ]
  }
}
Example Response
{
  "status_is_ok": true
}
 
Delete an invoice
DELETE /statements/{id}
Delete an invoice statement
URL Parameters
NameTypeRequiredParam TypeDescription
idstring
yespathInvoice ID
Example Response
{
  "status_is_ok": true
}
 
Support Tickets
API to retrieve, add, modify and remove support tickets associated with an account. This API can be used in lieu of integrating with a 3rd party support system to track support tickets at the account level.
 
Retrieve a ticket
GET /support_tickets/{ticket_id}
Returns info for an individual support ticket
URL Parameters
NameTypeRequiredParam TypeDescription
ticket_idstring
yespathTicket ID from support system
Example Response
{
  "status_is_ok": true, 
  "results": [
    {
      "ticket_id": "21623876121", 
      "account_id": "account_1", 
      "assignee_id": "45493", 
      "assignee_email": "Orelia.Langosh@dnb.com", 
      "type": "problem", 
      "state": "open", 
      "priority": "normal", 
      "create_time": 1410055451006, 
      "close_time": null, 
      "subject": "Aspernatur saepe reiciendis", 
      "description": "Deserunt non nisi at commodi."
    }
  ]
}
 
Bulk insert/modify tickets
POST /support_tickets
Insert/modify support tickets in bulk. Pagination is supported.
Body Parameters
NameTypeRequired
Insert / Modify
Description
ticket_idstring(80)
yes / yesTicket ID from support system
account_idstring(256)
yes / yesAccount ID of ticket requester
statestring(80)
yes / noTicket state; e.g., open, closed, solved, pending
subjectstring(128)
yes / noTicket subject
create_timelong
epoch milliseconds
yes / noTime at which the ticket was created
typestring(80)
no / noTicket type; e.g.: problem, incident, question, task
close_timelong
epoch milliseconds
no / noTime at which the ticket was closed
prioritystring(80)
no / noTicket priority; e.g., high, low, normal, urgent
assignee_idstring(128)
no / noID of ticket assignee in support system
assignee_emailstring(128)
no / noEmail of ticket assignee in support system
descriptionstring(8192)
no / noDescription of ticket
sourcestring(80)
no / noData source for record, e.g., CRM, etc.
csat_labelstring(80)
no / noCustomer satisfaction textual label, e.g., statisifed, unhappy
csat_valuelong
no / noCustomer satisfaction numeric value
last_update_timelong
epoch milliseconds
no / noTime at which ticket as last updated
Example Request
{
  "records": [
    {
      "ticket_id": "21623876183", 
      "account_id": "account_1", 
      "assignee_id": "45493", 
      "assignee_email": "Orelia.Langosh@dnb.com", 
      "type": "problem", 
      "state": "closed", 
      "priority": "normal", 
      "create_time": 1410055451006, 
      "close_time": 1411351451006, 
      "subject": "Beatae blanditiis", 
      "description": "Et et provident beatae blanditiis quae recusandae rerum."
    }, 
    {
      "ticket_id": "21623876121", 
      "account_id": "account_1", 
      "assignee_id": "45493", 
      "assignee_email": "Orelia.Langosh@dnb.com", 
      "type": "problem", 
      "state": "open", 
      "priority": "normal", 
      "create_time": 1410055451006, 
      "close_time": null, 
      "subject": "Aspernatur saepe reiciendis", 
      "description": "Deserunt non nisi at commodi."
    }
  ]
}
Example Response
{
  "status_is_ok": false, 
  "failed_results": [
    {
      "message": "'create_time' value must be a Long", 
      "status_is_ok": false, 
      "record": 2
    }
  ]
}
 
Modify a ticket
PUT /support_tickets/{ticket_id}
Modify an existing support ticket. See the POST request for the JSON body parameters.
URL Parameters
NameTypeRequiredParam TypeDescription
ticket_idstring
yespathTicket ID from support system
Example Request
{
  "data": {
    "ticket_id": "21623876183", 
    "account_id": "account_1", 
    "assignee_id": "45493", 
    "assignee_email": "Orelia.Langosh@dnb.com", 
    "type": "problem", 
    "state": "closed", 
    "priority": "normal", 
    "create_time": 1410055451006, 
    "close_time": 1411351451006, 
    "subject": "Beatae blanditiis", 
    "description": "Et et provident beatae blanditiis quae recusandae rerum."
  }
}
Example Response
{
  "status_is_ok": true
}
 
Delete a ticket
DELETE /support_tickets/{ticket_id}
Delete a support ticket
URL Parameters
NameTypeRequiredParam TypeDescription
ticket_idstring
yespathTicket ID from support system
Example Response
{
  "status_is_ok": true
}
 
Interactions
API to retrieve and add customer related interactions. Interactions may contain the contents of emails, phone calls, or other customer related discussions. Interactions (similar to Notes) are different from other objects within Natero, as some are generated solely within the Natero product and others are not. As such, interactions generated within Natero are associated with an internal ID (or just ID) and those generated externally have an external_id. The Interaction APIs allow for access via both of these IDs, as well, the external_id can be set on internally generated interactions via a PUT or POST call.
 
Retrieve an interaction
GET /interactions, /interactions/external_id, /interactions/{id}, /interactions/external_id/{external_id}
Retrieves either a single or a set of interactions. GET /interactions returns all interactions; GET /interactions/{id} returns a single interaction matching the specified Natero Internal ID. GET /interactions/external_id/ returns all interactions with NO external_id; GET /interactions/external_id/{id} returns a single interaction matching the specified external ID. All GET queries can be further filtered using the query parameters below (create_time filters by creation time, and account_id filters by account ID).
URL Parameters
NameTypeRequiredParam TypeDescription
idlong
nopathNatero internal ID (one of id or external_id must be given)
external_idstring
nopathExternal ID (one of id or external_id must be given)
account_idstring
noqueryAccount ID filter; return all interactions matching account_id
create_timelong
noqueryCreate time filter; return all interactions with a create time that is greater or equal
modify_timelong
noqueryModify time filter; return all interactions with a modify time that is greater or equal
 
Bulk insert/modify interactions
POST /interactions
Insert/modify interactions in bulk. Pagination is supported.
Body Parameters
NameTypeRequired
Insert / Modify
Description
idlong
no / noNatero internal ID (one of id or external_id must be given)
external_idstring(80)
no / noExternal ID (one of id or external_id must be given)
account_idstring(256)
yes / yesAccount ID
typestring(80)
yes / noType of interaction (e.g., email, in-person, phone, etc)
create_timelong
epoch milliseconds
yes / noTime that interaction was created
rep_emailstring(80)
no / noEmail address of rep that communicated with customer
rep_first_namestring(80)
no / noFirst name of rep that communicated with customer
rep_last_namestring(80)
no / noLast name of rep that communicated with customer
user_idstring(80)
no / noCustomer contact (CRM) user ID
userstring(80)
no / noCustomer contact name or email (if no CRM user ID specified)
detailsstring(262144)
no / noDetails of the interaction (message body)
subjectstring(128)
no / noSubject of the interaction
sourcestring(80)
no / noSource of last modification for the interaction (e.g., Salesforce, Intercom, etc)
is_htmlboolean
Default: false
no / noIs the interaction in html (true) or plain text (false)
 
Modify an interaction
PUT /interactions/{id}, /interactions/external_id/{external_id}
Insert/modify an interaction. See the POST request for the JSON body parameters.
URL Parameters
NameTypeRequiredParam TypeDescription
idlong
nopathNatero internal ID (one of id or external_id must be given)
external_idstring
nopathExternal ID (one of id or external_id must be given)
 
Delete an interaction
DELETE /interactions/{id}, /interactions/external_id/{external_id}
Delete an interaction either by internal or external ID.
URL Parameters
NameTypeRequiredParam TypeDescription
idlong
nopathNatero internal ID (one of id or external_id must be given)
external_idstring
nopathExternal ID (one of id or external_id must be given)
 
Notes
API to retrieve and add customer related notes. Notes may contain internal discussions, or record any type of information related to a specific account. Notes are similar to notes in that they are different from other objects within Natero, as some are generated solely within the Natero product and others are not. As such, notes generated within Natero are associated with an internal ID (or just ID) and those generated externally have an external_id. The Note APIs allow for access via both of these IDs, as well, the external_id can be set on internally generated notes via a PUT or POST call.
 
Retrieve a note
GET /notes, /notes/external_id, /notes/{id}, /notes/external_id/{external_id}
Retrieves either a single or a set of notes. GET /notes returns all notes; GET /notes/{id} returns a single note matching the specified Natero Internal ID. GET /notes/external_id/ returns all notes with NO external_id; GET /notes/external_id/{id} returns a single note matching the specified external ID. All GET queries can be further filtered using the query parameters below (create_time filters by creation time, and account_id filters by account ID).
URL Parameters
NameTypeRequiredParam TypeDescription
idlong
nopathNatero internal ID (one of id or external_id must be given)
external_idstring
nopathExternal ID (one of id or external_id must be given)
account_idstring
noqueryAccount ID filter; return all notes matching account_id
create_timelong
noqueryCreate time filter; return all notes with a create time that is greater or equal
modify_timelong
noqueryModify time filter; return all notes with a modify time that is greater or equal
 
Bulk insert/modify notes
POST /notes
Insert/modify notes in bulk. Pagination is supported.
Body Parameters
NameTypeRequired
Insert / Modify
Description
idlong
no / noNatero internal ID (one of id or external_id must be given)
external_idstring(80)
no / noExternal ID (one of id or external_id must be given)
account_idstring(256)
yes / yesAccount ID
create_timelong
epoch milliseconds
yes / noTime that note was created
rep_emailstring(80)
no / noEmail address of rep that created/modified the note
editor_first_namestring(80)
no / noFirst name of the person who created/modified the note (automatically filled in when rep_email is specified)
editor_last_namestring(80)
no / noLast name of the person who created/modified the note (automatically filled in when rep_email is specified)
notestring(32768)
no / noContents of the note
subjectstring(512)
no / noSubject of the note
sourcestring(80)
no / noSource of last modification for the interaction (e.g., Salesforce, Intercom, etc)
is_htmlboolean
no / noIs the note in html format?
 
Modify a note
PUT /notes/{id}, /notes/external_id/{external_id}
Modify an existing note by either the internal or external ID. See the POST request for the JSON body parameters.
URL Parameters
NameTypeRequiredParam TypeDescription
idlong
nopathNatero internal ID (one of id or external_id must be given)
external_idstring
nopathExternal ID (one of id or external_id must be given)
 
Delete a note
DELETE /notes/{id}, /notes/external_id/{external_id}
Delete an note either by internal or external ID.
URL Parameters
NameTypeRequiredParam TypeDescription
idlong
nopathNatero internal ID (one of id or external_id must be given)
external_idstring
nopathExternal ID (one of id or external_id must be given)
 
Search
API to retrieve objects filtered by specified conditions.
 
Retrieve objects
POST /search/{api}
Retrieve objects from specified API that match the conditions provided. Each record contains a condition that is evaluated against each object. All records matching all conditions are returned (each condition is ANDed with each other). Each record condition must contain an 'attribute' and a 'value' property. The attribute property contains the field to search for while the value contains the value of that field.

Supported APIs to search include:

  • 'accounts' - Account API (sub-objects including dimensions, nps history, stage history, csm assignment not searchable)
  • 'account_contacts' - Account contacts (sub-objects including dimensions not searchable)
  • 'account_users' - Account product users (sub-objects including dimensions not searchable)
Optionally, an 'operator' can be specified. If no operator is specified then exact equality is assumed.

Possible operators include:

  • 'eq' - equals (case sensitive for strings)
  • 'ne' - not equals (case sensitive for strings)
  • 'lt' - less than (numeric only)
  • 'le' - less than or equal (numeric only)
  • 'gt' - greater than (numeric only)
  • 'ge' - greater than or equal (numeric only)
  • 'like' - contains substring (case insensitive)
  • 'notLike' - does not contain substring (case insensitive)
  • 'isTrue' - is true (boolean only)
  • 'isFalse' - is false (boolean only)
Similar to other GET requests, Search requests support pagination using the 'page' query parameter. Likewise, Search responses use the GET response format:
{
  "current_page": 0, 
  "status_is_ok": true, 
  "results": [
  ]
}
Body Parameters
NameTypeRequired
Insert / Modify
Description
attributestring
no / noName of the attribute to match on. The attribute must match the attribute specified in the API.
valuestring,long,boolean
no / noValue used for comparison. Type depends on type of attribute.
operatorstring
Choices: eq,ne,lt,le,gt,ge,like,notLike,isTrue,isFalse
no / noOperator used to compare API's attribute to the value.
Example Request
Search /search/accounts for website containing 'natero.com' and current_nps_score >= 70
{
  "records": [
    {
      "attribute": "website", 
      "operator": "like", 
      "value": "natero.com"
    }, 
    {
      "attribute": "current_nps_score", 
      "operator": "ge", 
      "value": 70
    }
  ]
}
Example Response
Response to account search
{
  "current_page": 0, 
  "results": [
    {
      "account_id": "123456", 
      "billing_account_id": null, 
      "crm_account_id": null, 
      "csm_score": null, 
      "current_health_score": null, 
      "current_mrr": null, 
      "current_nps_score": 85, 
      "current_stage": null, 
      "is_active": true, 
      "is_churned": false, 
      "join_date": 1412685594018, 
      "name": "Natero", 
      "phone": null, 
      "renewal_date": null, 
      "support_account_id": null, 
      "tier": null, 
      "website": "http://www.natero.com"
    }
  ], 
  "status_is_ok": true
}
Example Request
Search /search/account_users looking for users with email containing '@natero.com'
{
  "records": [
    {
      "attribute": "email", 
      "operator": "like", 
      "value": "@natero.com"
    }
  ]
}