Octy API Reference

Welcome to Octy's API. This API can be used to access all of Octy's retention toolchain API endpoints. The Octy API is organized around REST. All requests must be made over an SSL protocol.

All request and response bodies are JSON encoded, including errors.


Each response will be returned with:

  • • a standard relevant HTTP status code.
  • • a request meta-object within the response body itself.
    • - containing the status of the request (Success/Failure).
    • - and a friendly message.

Explore the Octy API with our Postman collection:

Base URL : 
--
https://api.octy.ai
Octy API version :  v1 (0.9.0 [BETA])
--
Retention tool-chain api prefix : /v1/retention/
Authentication

2 API Keys, Public_key and Secret_key, are generated and sent to the account holder via email on the successful account creation. Requests are authenticated using HTTP basic access authentication. The Public Key must be provided as the basic authentication username and the Secret key must be provided as the basic authentication password. The Secret Key should be considered as a password as it allows full access to all account data and resource management and therefore must be kept secure and should only be shared with trusted, verified individuals/partners.


API Keys:

  • 1. Public_key (username)
  • 2. Secret_key (password)


CLI commands

Set authentication keys in CLI application

octy-cli auth -p {public key} -s {secret key}
Example API Keys : 
--
Public key
pk_9b2f17a3-4573-4a9b-9128-53ee910ef2

Secret key
sk_d93f42b9-b752-484f-9d5c-dafz98462c
Example Basic Auth token : 
--
-H Authorization :
Basic cGtfMmM5ZGU2YjNiYzQ3YjJiN2ZmNDBjYTA0NWJlNzY4YTY0ZjMwNDEyMDAzY2ZmMDQ0OTU0OWNiYjE1YTdjMjYxMGRkZjA6c2tfZjVhOTAxNjYzYjhkYzMyNDgyMDk5OTcwMjJlMGE2NTQxMjQ1NmVmNzM5NzA2YmE5NzQyYjk0YWUwZjI4MWEyNDUyOWQ=
Errors

The Octy API returns errors with the relevant standard HTTP error status code, a JSON encoded body describing the known errors and, where applicable, a link to find extended help for the error encountered. In most cases, resources can be created, updated, or deleted in batches.

To ensure single instances of invalid objects do not void the entire request, valid objects will be processed as expected. However, an error message, with the invalid object’s identifier, will be returned within one of the following lists, with the relevant response object.


Example:
"failed_to_create" : [{"identifier" : "id_1234", "error_message": ""}]
"failed_to_update" : [{"identifier" : "id_1234", "error_message": ""}]
"failed_to_delete" : [{"identifier" : "id_1234", "error_message": ""}]
Example Error object response : 
--


                        
Pagination

To effectively reduce response times and object sizes for GET requests, the API utilizes pagination.

Currently, pagination is available on the following requests:


  • • Retrieve Profiles
  • • Retrieve Items
  • • Retrieve Custom event type definitions
  • • Retrieve Segments
  • • Retrieve Templates

If no "?id" query string parameter is provided with any one of the above requests, a pagination cursor of type ‘integer’, must be supplied within the header of the request. Requests that have a pagination cursor provided, will return up to 100 results in the response body along with the response header '-H cursor' containing the pagination cursor's current position to be used as the subsequent request’s '-H cursor' value.


Example:


  • • '-H cursor : 0' - returns the first 99 results found
  • • '-H cursor: 100' - returns all results between 100 and 199
Example pagination request : 
--

GET /v1/retention/profiles HTTP/1.1
Host: api.octy.ai
cursor: 1
Authorization: Basic ...
Limits

Requests

Up to 120 API requests can be conducted per minute, per endpoint, per account. This limit can be increased when requested with a valid reason.


Resources

On request and at Octy’s discretion, each resource can have increased limits set for business logic reasons; predominantly to ensure accuracy, time and cost-effective model training. By limiting the amount of data allowed, you are more likely to ensure the data stored on Octy’s secure servers is the most relevant and up to date; meaning better results from model training. These limits can be increased if requested with a valid reason.


If you require an increase in the limits imposed on your account, please contact us at support@octy.ai The table below shows a breakdown of the limits applied to each resource.


Profiles
Total allowed count 10,000
Batch create limit 100
Batch update limit 100
Batch delete limit 100
Items
Total allowed count 400
Batch create limit 100
Batch update limit 100
Batch delete limit 100
Events
Total allowed custom event type count 100
Batch create custom event type limit 100
Batch delete custom event type limit 100
Total allowed events count 1,000,000
Batch create events limit 100
Segments
Total allowed segment definitions 25
Batch delete limit 100
Messaging
Total allowed message templates 50
Batch create message templates limit 100
Batch update message templates limit 100
Batch delete message templates limit 100
Message generation limit (per request) 100
Configurations Logo

Configurations must be set both on accounts and on algorithms in order for Octy’s back-end systems to work correctly. This action must be conducted immediately after account creation. Configurations can be updated by using either the account/set endpoint, or algorithms/set endpoint.


Note that when updating configurations:

  • • It has a direct impact on training jobs, predictions, and notifications.
  • • all values must be supplied.
  • • configurations are completely overwritten with the provided data in the body of each /set request.
Configurations endpoints : 
--
GET  /configurations/account
POST /configurations/account/set

GET  /configurations/retention/algorithms
POST /configurations/retention/algorithms/set
Account Configurations


Set Account config

If existing account configurations exist, set-account-configurations will overwrite them.


Parameters
contact_name string
Required
The first name of the primary contact.
contact_surname string
Required
The family name of the primary contact.
contact_email_address string
Required
The email address of the primary contact.
webhook_url string
Required
Notification webhook URL.
Returns
New account configurations; Returns the new account configurations that have been set.


CLI commands
octy-cli config account -o set -n Arthur -f Fleck -e a.fleck@jokemail.com -w https://somewebhookurl.com
Set account configuration request: 
--
POST /v1/configurations/account/set HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"contact_name" : "Arthur",
"contact_surname" : "Fleck",
"contact_email_address" : "a.fleck@jokemail.com",
"webhook_url" : "https://somewebhookurl.com"
}
RESPONSE: 
--


                    
Retrieve Account config

If no account configurations are set, retrieve-account-configuration request will return an error.


Parameters
None
Returns
Current account configurations; Returns the existing/current account configurations.


CLI commands
octy-cli config account -o get
Retrieve account configuration request: 
--
GET /v1/configurations/account HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...
RESPONSE: 
--


                    
Algorithm Configurations


Set Recommendations config

If existing recommendations configurations exist, recommendations-configuration will overwrite them.


Parameters
algorithm_name string
Required
Shorthand name of the algorithm for which you are setting configurations. rec
recommend_interacted_items bool
Required
Recommend items that the customer has already purchased.
item_id_stop_list list - strings
Required
A list of item_ids (representing active existing items) that will not be recommended under any circumstances. An empty array '[]' can be supplied as the value for this parameter if you intend to maintain an empty stop list. Only active, existing items can be added to this list.
profile_features list - strings
Required
A list of profile features to be used in the next training dataset.
Returns
New recommendations algorithm configurations; Returns the new recommendations algorithm configurations that have been set.


CLI commands
octy-cli config algorithm -o set -a rec -r {true/false} -s {item id} -s {item id}... -p {profile feature} -p {profile feature}...
Set recommendations algorithm configuration request: 
--
POST /v1/configurations/retention/algorithms/set HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"algorithm_name": "rec",
"configurations": {
    "recommend_interacted_items": false,
    "item_id_stop_list": [
        "6f8095de2735228f5325"
    ],
    "profile_features":[
        "visits",
        "balance"
        ]
    }
}
RESPONSE: 
--


                    
Set Churn prediction config

If existing churn prediction configurations exist, set-churn-prediction-configurations will overwrite them.


Parameters
algorithm_name string
Required
Shorthand name of the algorithm for setting configurations. churn
profile_features list - strings
Required
A list of profile features to be used in the next training dataset.
Returns
New churn prediction algorithm configurations; Returns the new churn prediction algorithm configurations that have been set.


CLI commands
octy-cli config algorithm -o set -a churn -p {profile feature} -p {profile feature}...
Set Churn prediction algorithm configuration request: 
--
POST /v1/configurations/retention/algorithms/set HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"algorithm_name": "churn",
"configurations": {
    "profile_features":[
        "visits",
        "balance"
    ]
}
}
RESPONSE: 
--


                    
Retrieve Algorithm configs

Retrieves the algorithm configurations that are currently set for each algorithm. If no algorithm configurations are set, retrieve-algorithm-configuration will return an error.


Parameters
None
Returns
Algorithm configurations that are currently set.


CLI commands
octy-cli config algorithm -o get
Retrieve algorithm configuration request: 
--
GET /v1/configurations/retention/algorithms HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...
RESPONSE: 
--


                
Profiles Logo

At the centre of Octy's retention toolchain are profiles; anonymised representations of the customer. Once a profile has accumulated enough events and segmentation data, it will be further populated with model predictions and segmentation tags. This will give you a clearer picture of the customer on a granular level; allowing you to understand their behaviours, needs and ideal item recommendations. Profiles can be retrieved and filtered using a combination of query string parameters, allowing you to quickly target the customer who meets a very specific criteria.

The Profiles API allows you to retrieve, create, update and delete customer profiles. The example profile object below illustrates the attributes that Octy can add to the customer data.

Profiles endpoints : 
--
GET  /profiles
POST /profiles/create
POST /profiles/update
POST /profiles/delete
The Profile object

Attributes
profile_id string Octy generated identifier representing a profile.
customer_id string User supplied identifier representing a customer.
profile_data User specified key : value pairs relating to your customers attributes. Example: “gender” : “female”. In the event that a new key : value pair is specified, the data type of the value must be consistent with all future instances of this key across all other profiles.
platform_info User specified key : value pairs relating to your customers platform information. Example: “operating system” : “iOS”. In the event that a new key : value pair is specified, the data type of the value must be consistent with all future instances of this key across all other profiles.
segment_tags list - objects A list of segment tag objects that apply to the customer profile.
rfm_score int Profiles calculated RFM score relative to other active profiles.
rfm_description string Human readable description of profiles rfm score.
churn_probability string Human readable representation of the predicted churn probability score.
has_charged boolean Is this a paying customer; did the customer complete a charged event? This is automatically updated to 'true' if a charged event occurs on an existing Octy customer profile.
status string The status of the profile; ‘active’, ‘inactive’, ‘churned’. Set by default to 'active'.
created_at string Date and time that the profile was created.
last_updated string Date and time that the profile was last updated.
Example profile object: 
--


                    
Retrieve Profiles

Retrieve profiles by either:

  • • supplying a single or a combination of the allowed query string parameter(s)

  • • by providing a pagination cursor.


Parameters [query string]
id string
Optional
Octy profile_id or the customer_id reference. If this parameter is provided, all others will be ignored.
rfm int-int
Optional
Two integers separated by a single dash, representing the lower and upper rfm score filters (between 111 & 444).
churn_prob string
Optional
Shorthand description of the desired churn probability filter. (Accepted parameters - low, mid, mid-high, high, top-high).
segments list
Optional
A list of active segment tags separated by commas.

Headers
cursor int
Required if no id parameter supplied
Pagination cursor

Returns one of the following:
  • • Array of customer profile objects that meet the requests filtered or unfiltered criteria, including the count of returned profiles.
  • • Error message (if no profiles found with matching criteria).
Retrieve single profile request: 
--
GET /v1/retention/profiles?id=020200029390000000 HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...


Retrieve profiles request: 
--
GET /v1/retention/profiles?rfm=100-140&churn_prob=mid&segments=best_customers,top_spenders HTTP/1.1
Host: api.octy.ai
cursor: 1
Authorization: Basic ...
RESPONSE: 
--


                    
Create Profiles

Create up to 100 profiles in one batch with any single request.


Parameters
customer_id string
Required
User supplied customer identifier.
has_charged boolean
Required
Is this a paying customer; did the customer complete a charged event?
profile_data
Required
User specified key : value pairs relating to your customers attributes. Example: “gender” : “female”. In the event that a new key : value pair is specified, the data type of the value must be consistent with all future instances of this key across all other profiles.
platform_info
Required
User specified key : value pairs relating to your customers platform information. Example: “operating system” : “iOS”. In the event that a new key : value pair is specified, the data type of the value must be consistent with all future instances of this key across all other profiles.

Returns one of the following:
  • • Array of customer profile objects that have been successfully created, including the count of newly created profiles.
  • • Array of profiles that could not be created + Error message.
  • • Error message (if no customer profiles could be created).


CLI commands
octy-cli batch-create -t profiles -f {path/to/profiles_file.csv}
Create profiles request: 
--
POST /v1/retention/profiles/create HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

{
"profiles" : [
    {
    "customer_id" : "020200029388899",
    "has_charged" : true,
    "profile_data" : {
        "age" : 56
    },
    "platform_info" : {
        "os": "windows"
        }
    }
]
}
RESPONSE: 
--


                    
Update Profiles

Update up to 100 profiles in one batch with any single request. All values must be provided in order to update an existing customer profile.


Parameters
profile_id string
Required
Octy generated identifier representing a profile.
customer_id string
Required
User supplied identifier representing a customer.
has_charged boolean
Required
Is this a paying customer; did the customer complete a charged event?
profile_data
Required
User specified key : value pairs relating to your customers attributes. Example: “gender” : “female”. In the event that a new key : value pair is specified, the data type of the value must be consistent with all future instances of this key across all other profiles.
platform_info
Required
User specified key : value pairs relating to your customers platform information. Example: “operating system” : “iOS”. In the event that a new key : value pair is specified, the data type of the value must be consistent with all future instances of this key across all other profiles.
status string
Required
The current status of the profile; ‘active’, ‘inactive’, ‘churned’. (Updating this will have a direct effect on the profile being included in training data).

Returns one of the following:
  • • Array of updated customer profile objects.
  • • Array of profiles that could not be updated + Error message.
  • • Error message (if no profiles updated with request, error returned).
Update profiles request: 
--
POST /v1/retention/profiles/update HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"profiles": [
    {
        "profile_id": "profile_b29440dd9a3d739ab51d17d60598359c...",
        "customer_id": "020200029388899",
        "profile_data": {
            "age": 56,
            "gender": "male"
        },
        "platform_info": {
            "os": "windows",
            "browser": "chrome"
        },
        "status": "active",
        "has_charged": true
    }
]
}
RESPONSE: 
--


                    
Delete Profiles

Delete up to 100 profiles in a batch with any single request.


Parameters
profiles list - strings
Required
List of strings; Octy generated identifiers representing each profile.

Returns one of the following:
  • • Array of deleted customer profile ids.
  • • Array of profiles that could not be deleted + Error message.
  • • Error message (if no profiles are found with the profile_ids that were provided).
Delete profiles request: 
--
POST /v1/retention/profiles/delete HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"profiles" : [
 "profile_b29440dd9a3d739ab51d17d60598359c14acdd47a..."
]
}
RESPONSE: 
--


                    
Items Logo

Items are structured representations of the products your business sells. Item data is used in various training data sets for different models within the Octy platform. Notably, items are used for item recommendations, both directly and within message templates that utilise the recommendations system. Item data must be kept up-to-date to ensure accurate model training and relevant predictions.

The Items API allows you to retrieve, create, update and delete items.

Items endpoints : 
--
GET  /items
POST /items/create
POST /items/update
POST /items/delete
The Item object

Attributes
item_id string User supplied item identifier.
item_category string The category where the item belongs.
item_name string The item’s title.
item_description string The item’s short description. Maximum 40 characters.
item_price int The item's price is in the lowest denomination of customer’s currency.
status string The status of the item; ‘active’ or ‘inactive’. Set by default to 'active'.
created_at string Date and time that the item was created.
last_updated string Date and time that the item was last updated.
Example item object: 
--



                    
Retrieve Items

Retrieve multiple or singular item objects.

Retrieve items by either:

  • • supplying a single allowed query string parameter

  • • by providing a pagination cursor.


Parameters [query string]
id string
Optional
User supplied item identifier.

Headers
cursor int
Required if no id param supplied
Pagination cursor

Returns one of the following:
  • • Array of item objects that meet the requests filtered or unfiltered criteria, including the count of returned items.
  • • Error message (if no items found with matching criteria).
Retrieve single item request: 
--
GET /v1/retention/items?id=04fe4c38af34ec34cb47 HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...


Retrieve items request: 
--
GET /v1/retention/items HTTP/1.1
Host: api.octy.ai
cursor: 1
Authorization: Basic ...
RESPONSE: 
--


                    
Create Items

Create up to 100 items in one batch with any single request.


Parameters
item_id string
Required
User supplied item identifier.
item_category string
Required
The category where the item belongs.
item_name string
Required
The item’s title.
item_description string
Required
Item’s short description. Maximum 40 characters.
item_price int
Required
The item’s price, in the lowest denomination of customer’s currency.

Returns one of the following:
  • • Array of item objects that have been successfully created, including the count of newly created items.
  • • Array of items that could not be created + Error message.
  • • Error message (if no items were created).


CLI commands
octy-cli batch-create -t items -f {path/to/items_file.csv}
Create items request: 
--
POST /v1/retention/items/create HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

{
"items" : [

    {
        "item_id": "085085039453322",
        "item_category": "music",
        "item_name": "drum kit",
        "item_description": "smashing drums",
        "item_price": 45000
    }
]
}
RESPONSE: 
--


                    
Update Items

Update up to 100 items in one batch with any single request. All values must be provided in order to update existing items.


Parameters
item_id string
Required
User supplied item identifier.
item_category string
Required
The category where the item belongs.
item_name string
Required
The item’s title.
item_description string
Required
Item’s short description. Maximum 40 characters.
item_price int
Required
The item’s price, in the lowest denomination of customer’s currency.
status string
Required
The current status of the item. ‘active’ or ‘inactive’. (Updating this will have a direct effect on the item being included in training data).

Returns one of the following:
  • • Array of updated item objects if update is successful.
  • • Array of items that could not be created + Error message.
  • • Error message (if no items found with provided item_ids).
Update items request: 
--
POST /v1/retention/items/update HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"items" : [

    {
        "item_id" : "085085039453322",
        "item_category": "music",
        "item_name": "premium drum kit",
        "item_description": "smashing drum kit",
        "item_price": 80000,
        "status" : "active"
    }
    
]
}
RESPONSE: 
--


                    
Delete Items

Delete up to 100 items in one batch with any single request.


Parameters
items list - strings
Required
List of user supplied item identifiers.

Returns one of the following:
  • • Array of deleted item_ids.
  • • Array of items that failed to delete + Error message.
  • • Error message (if no items found with provided item_ids).
Delete items request: 
--
POST /v1/retention/items/delete HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"items" : [

  "085085039453322"

]
}
RESPONSE: 
--


                    
Events Logo

The Events API can be broken down into two sub categories:

Custom event types: Custom event types are user defined descriptions, allowing you to track instances of this type.

Event instances: Event objects representing occurrences of events. The data aggregated in event instances is used both for training datasets and plays a fundamental role in profile segmentation.


Octy has two predefined system event types; Charged and Churned. Unlike custom event types, system event types are used to trigger specific actions against the customer profile that performs either system event type. The Events API allows you to retrieve, create, update and delete custom event types in addition to creating event instances. Event instances can be recorded as they occur or backdated and created in batches.


Charged: If a profile performs a 'charged' event, the 'is_charged' attribute of that profile will be updated to 'true' if it is not set already.

Churned: If a profile performs a ‘churned’ event, the status attribute of that profile will be updated to ‘churned’.

Events endpoints : 
--
GET  /events/types
POST /events/types/create
POST /events/types/delete

POST /events/create
POST /events/create/batch
The Custom event type object

Attributes
event_type_id string Octy generated identifier representing custom event type.
event_type string The name of the custom event type. Used to track occurrences of this event type.
event_properties list - strings List of the names of required keys to be used when tracking events of this type.
created_at string Date and time that the custom event type was created.
Example custom event type object: 
--


                
Retrieve Custom event type definitions

Retrieve multiple or singular custom event type objects.

Retrieve Custom event type definitions by either:

  • • supplying a single allowed query string parameter.

  • • by providing a pagination cursor.


Parameters [query string]
id string
Optional
Octy generated identifier representing custom event type.

Headers
cursor int
Required if no id param supplied
Pagination cursor

Returns one of the following:
  • • Array of custom event type objects that meet the requests filtered or unfiltered criteria, including the count of returned custom event types.
  • • Error message (if no custom event types found with matching criteria).


CLI commands
octy-cli event-types -o get -e {id}[optional]
Retrieve single custom event type request: 
--
GET /v1/retention/events/types?id=custom_event_type_4619f5b66a98fe215417ca61e5a44a5e7200d08581af7d7af25522ae74fcdfde6ed2 HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...


Retrieve custom event types request: 
--
GET /v1/retention/events/types HTTP/1.1
Host: api.octy.ai
cursor: 1
Authorization: Basic ...
RESPONSE: 
--


                
Create custom event type

Create custom event type definitions.


Parameters
event_type string
Required
The name of the custom event type.
event_properties list - string
Required
Name of required keys to be used when tracking event instances of this type.

Returns one of the following:
  • • Array of custom event type objects that have been successfully created, including the count of newly created custom event types.
  • • Array of custom event types that could not be created + Error message.
  • • Error message (if no custom event types could be created).


CLI commands
octy-cli event-types -o set -e {event_type} -p {event_property} -p {event_property}...
Create custom event type request: 
--
POST /v1/retention/events/types/create HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

{
"event_types" : [
    
    {
        "event_type" : "login",
        "event_properties" : [
            "device"
        ]
    }
    
]
}
RESPONSE: 
--


                
Delete custom event type

Delete up to 100 custom event types in one batch with any single request.


Parameters
event_type_ids list - strings
Required
List of Octy generated identifiers representing each custom event type.

Returns one of the following:
  • • Array of deleted custom event types.
  • • Array of failed to delete custom event types + Error message.
  • • Error message (if no items found with provided event_type_id).


CLI commands
octy-cli event-types -o delete -t {event_type_id} -t {event_type_id}...
Delete custom event types request: 
--
POST /v1/retention/events/types/delete HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"event_type_ids" : [
    "custom_event_type_26bbd0add89a27e6a29065fd5876bf607e3233aa5a92754454937d1c87ed33690305"
]
}
RESPONSE: 
--


                
The event object

Attributes
event_id string Octy generated identifier representing event.
event_type string The type of the event conducted by a profile.
event_properties keys : values Required key : value pairs for this event type.
profile_id string Octy generated identifier representing the profile that conducted this event.
created_at string Date that the time event instance was created.
Example event object: 
--


                
Create event

Create an event instance of a specified event-type for a specific profile.


Parameters
event_type string
Required
The name of the custom event type.
event_properties keys : values
Required
The required key : value pairs for the specified event type. Once the value for an event property is provided with the first instance of an event-type, the data type provided with all future instances of this event properties value must be consistent.
profile_id string
Required
The id of the profile conducting the event.

Returns
Summary of created event.
Create event request: 
--
POST /v1/retention/events/create HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

{
"event_type": "page_view",
"event_properties": {
    "page_id" : "homepage"
},
"profile_id" : "profile_0d8bc52525ff5569047b7e888f85ecef368d12911de2fd0e8f47a6f6e58f6a734cb1"
}
RESPONSE: 
--


            
Batch create events

Batch creates events for one or more profiles. This is useful for creating backdated events.


Parameters
event_type string
Required
The name of the custom event type.
event_properties keys : values
Required
The required key : value pairs for the specified event type.
profile_id string
Required
The id of the profile conducting the event.
created_at string
Optional
Date and time that the event was created. Must be in the following format: 'YYYY-MM-DD HH:MM:SS'. If left blank, the created_at attribute will be set to the current date and time.

Returns one of the following:
  • • Array of created events, including total count.
  • • Array of events that could not be created + Error message.
  • • Error message (if no events are created).


CLI commands
octy-cli batch-create -t events -f {path/to/events_file.csv}
Create batch events request: 
--
POST /v1/retention/events/create/batch HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

{ 
"events" : [
    {
        "event_type": "page_view",
        "event_properties": {
            "page_id" : "contact"
        },
        "profile_id" : "profile_0d8bc52525ff5569047b7e888f85ec...",
        "created_at" : ""
    }
]
}
RESPONSE: 
--


            
Segments Logo

Segment definitions are a way of grouping profiles based on common profile characteristics and behaviours, allowing you to hyper-target your outreach, content and messaging; reducing unnecessary advertisement/customer-retention spend.

There are two key segment types; live and past. Live segments allow you to segment profiles in real time based on events, whereas, past segments allow you segment profiles based on past events data. Both live and past segments definitions have a set of sub types that must be provided when creating a new segment definition.

This is explained in detail in the segmentation section of the documentation.

The Segments API allows you to retrieve, create and delete segment definitions.

Segments endpoints : 
--
GET  /segments
POST /segments/create
POST /segments/delete
The Segment object

Attributes
segment_id string Octy generated identifier representing the segment.
segment_name string The friendly name of the segment.
segment_type string The primary type of the segment; ‘live’ or ‘past’.
segment_sub_type int The numerical sub type of the segment; 1-4.
segment_timeframe int The number of days in which the specified action(s) or action(s)+inaction(s) within the event sequence is expected to have occurred.
events_sequence list The sequence of action or inaction events that define the criteria for this segment.
↳ event_type string The name of the specified ‘event’ i.e. custom event type or system event type.
↳ exp_timeframe int The time interval between this event and the subsequent event in minutes. Must be set as ‘0’ if no subsequent events, or segment_type is 'past'.
↳ action_inaction string Dictates whether this event should have occurred - action or an inaction.
↳ event_properties keys : values Selected key : value pair(s). Keys must exist within the specified event-type event_properties attribute.
profile_property_name string The name of the key that should exist in a profile’s profile_data to make the profile eligible for this segment.
profile_property_value any The value that should exist in a profile’s profile_data, relevant to the specified profile_property_name.
profile_count string The number of profiles that currently meet this segment's criteria. This applies to past segments only. Will return a value of 0 for live segment definitions.
created_at string Date and time that the event was created.
Example segment object: 
--


                    
Retrieve Segments

Retrieve multiple or singular segment objects. Retrieve segments by either:

  • • supplying a single allowed query string parameter.

  • • by providing a pagination cursor.


Parameters [query string]
id string
Optional
Octy generated identifier, representing the segment (segment_id) or the friendly name of the segment (segment_name).

Headers
cursor int
Required if no id param supplied
Pagination cursor

Returns one of the following:
  • • Array of segment objects that meet the requests filtered or unfiltered criteria, including the count of returned segments.
  • • Error message (if no segments found with matching criteria).


CLI commands
octy-cli segments -o get
octy-cli segments -o get -i {id}[optional]
Retrieve single segment request: 
--
GET /v1/retention/segments?id=Best customers HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...


Retrieve segments request: 
--
GET /v1/retention/segments HTTP/1.1
Host: api.octy.ai
cursor: 1
Authorization: Basic ...
RESPONSE: 
--


                    
Create Segment

Create a singular segment definition.


Parameters
segment_name string
Required
The friendly name of the segment.
segment_type string
Required
The primary type of the segment; live or past.
segment_sub_type int
Required
The numerical sub type of the segment; 1-4.
segment_timeframe int
Required
The number of days in which the specified action(s) or action(s)+inaction(s) within the event sequence is expected to have occurred. Must be '0' if segment_type is ‘live’.
event_sequence list
Required
The sequence of action or inaction events that define the criteria for this segment.
↳ event_type string
Required
The name of the custom event type or system event type.
↳ exp_timeframe int
Required
The time interval between this event and the subsequent event in minutes. Must be set as ‘0’ if no subsequent events, or segment_type is 'past'.
↳ action_inaction string
Required
Dictates whether this event should have occurred - action or an inaction.
↳ event_properties keys : values or null
Required
Selected key : value pair(s). Keys must exist within the specified event-type event_properties attribute.
profile_property_name string
Optional
The name of the key that should exist in a profile’s profile_data attribute to make a profile eligible for this segment. Required if 'past' segment is of sub type ‘3’ or ‘4’.
profile_property_value any
Optional
The value that should exist in a profile’s profile_data attribute, relevant to the specified profile_property_name. The data type provided for this parameter should match that of the intended profile_data attribute. Required if 'past' segment is of sub type 3 or 4.

Returns one of the following:
  • • Created (if the segment type is ‘live’; returns a summary of newly created segment).
  • • Processing (if segment type is 'past', the segmentation process will be initiated on past events).
Create a segment request: 
--
POST /v1/retention/segments/create HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

//PAST SEGMENT EXAMPLE:
{
"segment_name" : "Best customers", 
"segment_type" : "past",
"segment_sub_type" : 1,
"segment_timeframe" : 30,
"event_sequence" : [
    {
        "event_type": "page_view",
        "exp_timeframe": 0,
        "action_inaction": "action",
        "event_properties": {
            "page_id": "checkout"
        }
    }
    ],
"profile_property_name":  "level",
"profile_property_value" : "gold"
}

//LIVE SEGMENT EXAMPLE:
{
"segment_name" : "Dropped cart", 
"segment_type" : "live",
"segment_sub_type" : 2,
"segment_timeframe" : 0,
"event_sequence" : [
    {
        "event_type": "page_view",
        "exp_timeframe": 120,
        "action_inaction": "action",
        "event_properties": {
            "page_id": "checkout"
        }
    },
    {
        "event_type": "charged",
        "exp_timeframe": 0,
        "action_inaction": "inaction",
        "event_properties": {
            "item_id": "1232435351424",
            "payment_method" : "visa"
        }
    }
    ]
}
RESPONSE: 
--


                    
Delete Segments

Delete up to 100 segments in one batch with any single request.


Parameters
segments list - strings
Required
List of Octy generated identifiers representing segments (segment_id).

Returns one of the following:
  • • Array of deleted segment_ids.
  • • Array of failed to delete segments + Error message.
  • • Error message (if no segments found with provided segment_ids).
Note: Segments are not deleted immediately, as they may be required for predictions on the current trained models. All 'flagged' segments will be deleted on completion of the next relevant training jobs.

CLI commands
octy-cli segments -o delete -s {segment id} -s {segment id}...
Delete segments request: 
--
POST /v1/retention/segments/delete HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"segments" : [

    "segment_054cd5690540f9f8330dcf811fdaaa9717b8743f42c10a7c0224f0e6bdb4a3634301"
    
]
}
RESPONSE: 
--


                    
Messaging Logo

The Octy messaging API utilises message content templates: the most basic but robust form of natural language generation. Creating message templates allows you to generate personalised messages at scale and in seconds.

Messaging endpoints : 
--
GET  /messaging/templates
POST /messaging/templates/create
POST /messaging/templates/update
POST /messaging/templates/delete

POST /messaging/content/generate
The Template object

Attributes
template_id string Octy generated identifier representing the template.
friendly_name string The template’s friendly name.
template_type string User supplied; template type; used for filtering and user reference.
title string The subject line or title of the content.
content string The template’s structured content, including any placeholder tags.
required_data list - strings A list of the placeholder tags specified in the content.
default_values keys : values A key : value pair for each specified placeholder tag and its corresponding default value. All provided values must be of type ‘string’.
created_at string Date and time that the template type was created.
last_updated string Date and time that the template was last updated.
Example template object: 
--


                
Retrieve Templates

Retrieve multiple or singular template objects. Retrieve templates by either:

  • • supplying a single allowed query string parameter

  • • by providing a pagination cursor.


Parameters [query string]
id string
Optional
Octy generated identifier, representing template (template_id) or the friendly name of the template (friendly_name) or a previously specified template_type to return all templates of this type.

Headers
cursor int
Required if no id parameter supplied
Pagination cursor

Returns one of the following:
  • • Array of template objects that meet the request filtered or unfiltered criteria.
  • • Error message (if no templates are found with matching criteria).


CLI commands
octy-cli templates -o get
octy-cli templates -o get -t {id}[optional]
Retrieve single template request: 
--
GET /v1/retention/messaging/templates?id=Spring campaign HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...


Retrieve templates request: 
--
GET /v1/retention/messaging/templates HTTP/1.1
Host: api.octy.ai
cursor: 1
Authorization: Basic ...
RESPONSE: 
--


                
Create Templates

Creates message template(s).

ITEM_REC is a placeholder tag within the ‘content’ parameter of the template. Example : content : “We have a deal on {ITEM_REC}”. Default values can NOT be set for ITEM_REC placeholder tags. On content generation, where possible, ITEM_REC placeholders will be populated with the name of the highest scoring recommended item for each supplied profile_id.


Parameters
friendly_name string
Required
The template's friendly name.
template_type string
Required
User supplied template type. Used for filtering and user reference.
title string
Required
The subject line or title of the content.
content string
Required
The template's structured content, including any placeholder tags.
required_data list - strings
Required
A list of the placeholder tags specified in the content, not including any ITEM_REC tags.
default_values keys : values
Required
A key : value pair for each specified placeholder tag and its corresponding default value. All values must be of type ‘string’.

Returns one of the following:
  • • Array of template_ids and friendly_names that have been successfully created.
  • • Array of template_ids and friendly_names that could not be created + Error message.
  • • Error message (if no templates could be created).
Create template request: 
--
POST /v1/retention/messaging/templates/create HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

{
"templates": [
    {
        "friendly_name": "Winter season campaign",
        "template_type": "email",
        "title": "Some cool deals",
        "content": "Hey {first_name}, We think you might like our deals on {ITEM_REC}",
        "required_data": [
            "first_name"
        ],
        "default_values": {
            "first_name": "there"
        }
    }
]
}
RESPONSE: 
--


                
Update Templates

Batch update message templates. All values must be provided to perform an update.


Parameters
template_id string
Required
Octy generated identifier representing the template.
friendly_name string
Required
The template's friendly name.
template_type string
Required
User supplied template type. Used for filtering.
title string
Required
The subject line or title of the content.
content string
Required
The template's structured content, including any placeholder tags.
required_data list - strings
Required
A list of the placeholder tags specified in the content, not including any ITEM_REC tags.
default_values keys : values
Required
A key : value pair for each specified placeholder tag (key) and its corresponding default value (value). All values must be of type ‘string’.

Returns one of the following:
  • • Array of template_ids that have successfully updated.
  • • Array of template_ids that could not be updated + Error message.
  • • Error message (if no templates could be updated).
Update template request: 
--
POST /v1/retention/messaging/templates/update HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

{
"templates": [
{
    "template_id" : "template_22b25c07efaf340d0e36572e0b10d55f731e768ca1c0275c922c8e8cf152b02dc8ad",
    "friendly_name": "Winter season campaign 2020",
    "template_type": "email",
    "title": "Some cool deals",
    "content": "Hey {first_name} {last_name}, We think you might like our deals on {ITEM_REC}",
    "required_data": [
        "first_name",
        "last_name"
    ],
    "default_values": {
        "first_name": "there",
        "last_name" : "friend"
    }
}
]
}
RESPONSE: 
--


            
Delete Templates

Delete up to 100 templates in one batch with any single request.


Parameters
template_ids list - strings
Required
List of Octy generated identifiers representing each template.

Returns one of the following:
  • • Array of deleted template_ids.
  • • Array of templates that could not be deleted + Error message.
  • • Error message (if no items found with provided template_ids).


CLI commands
octy-cli templates -o delete -t {template_id} -t {template_id}...
Delete templates request: 
--
POST /v1/retention/events/delete HTTP/1.1
Host: api.octy.ai
Content-Type: application/json
Authorization: Basic ...

{
"template_ids" : [
    "template_22b25c07efaf340d0e36572e0b10d55f731e768ca1c0275c922c8e8cf152b02dc8ad"
    ]
}
RESPONSE: 
--


                
The Message object

Attributes
template_id string Octy generated identifier representing the template used to generate this message content.
friendly_name string The friendly name of the template used to generate this message content.
title string The title of the generated message content.
content string The complete generated message content, containing populated values.
Example message object: 
--


                
Generate Content

Generate message content for multiple profiles and multiple templates.


Parameters
template_id string
Required
The Octy generated identifier representing the template to be used to generate message content.
item_recommendation boolean
Required
  • Template uses item recommendations.
  • True - template contains ITEM_REC placeholder tag
  • False - template does not contain ITEM_REC placeholder tag
data keys : values
Required
The required_data keys and desired values used to populate the specified message template. Any missing values will be replaced with the relevant default values defined in the specified template. As a minimum requirement, all of the specified templates required_data keys must be supplied with an empty string as the value. Must contain a "profile_id" : "profile_232424331324..." key : value pair if template contains ITEM_REC placeholder tag.

Go here for more on using this feature.


Returns one of the following:
  • • Array of message objects that have been successfully generated, including the count of generated messages.
  • • Array of messages that could not be generated + Error message.
  • • Array of templates for messages that could be generated + Error message.
Generate message content request: 
--
POST /v1/retention/messaging/content/generate HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...


//WITHOUT ITEM RECOMMENDATIONS

{
"messages" : [
    {
    "template_id" : "template_75869768...",
    "item_recommendation" : false,
    "data" : [ 	
              { 	
                "first_name" : "Jamie",
                ... other parameters required for specified template						      
              },
              { 	
                "first_name" : "Brendan",
                ... other parameters required for specified template						      
              }
        ]
    }
]
}


//WITH ITEM RECOMMENDATIONS

{
"messages" : [
    {
    "template_id" : "template_0309849303...",
    "item_recommendation" : true,
    "data" : [ 	
             { 	
                "first_name" : "Ben",
                ... other parameters required for specified template 
                "profile_id" : "profile_8c2678ee5abaf76105eef5..." 						      
             },
             { 	
                "first_name" : "Saleena",
                ... other parameters required for specified template 
                "profile_id" : "profile_ea0a534f5be61405636882..." 						      
             }
        ]
    }
]
}
RESPONSE: 
--


            
Recommendations Logo

Our recommendations models are trained using a hybrid recommendations system. This is one of the most powerful recommendations systems currently available. Recommendation models are trained and updated at regular short term intervals to ensure the items recommended are as relevant as possible. Items are recommended not only based on each profile's previous interactions, but also on the interactions of similar profiles.

The recommendations system will return up to 10 item recommendations per profile identifier provided within the body of a request, each with a score representing the likelihood a profile will purchase this item.

The Recommendations API allows you to retrieve item recommendation predictions.

Recommendations endpoints : 
--
POST  /recommendations
The Recommendation object

Attributes
profile_id string Octy generated identifier representing the profile.
recommendations list - objects Order descending list, by score of each item recommendation. A maximum of 10 item recommendations returned per provided profile_id.
↳ item_id string User supplied item identifier.
↳ score float The score relative to probability of suitability of this recommendation.
error string Any error that occurred during item recommendations for this profile.
Example recommendation object: 
--


                
Predict Recommendations

Predict item recommendations for each valid profile_id provided.


Parameters
profile_ids list - strings
Required


Returns one of the following:
  • • Array of item recommendation objects.
  • • Error message (if unable to make recommendation predictions for any provided profile_ids).
  • Also returns the meta data on the recommendations training job and the trained model used for predictions.
Predict recommendations request: 
--
POST /v1/retention/recommendations HTTP/1.1
Host: api.octy.ai
Authorization: Basic ...

{
"profile_ids" : [
"profile_3a86efcc1b5630f42406b80783fd86e4f378e2fa9cd440c3ee0b058b08dd212b42c1"
]
}
RESPONSE: 
--


                
Churn prediction report

In addition to a churn prediction score being applied to each profile, Octy has the ability to generate a comprehensive churn prediction report, highlighting the most prominent characteristics and behaviours that contribute to customer churn.

The Churn prediction API allows you to generate and retrieve a churn prediction report.

Churn prediction endpoints : 
--
GET  /churn_prediction/report
The Churn prediction report object

Attributes
training_job_data keys : values Training job metadata.
↳ training_job_id string Octy generated identifier representing training job.
↳ model_accuracy float The accuracy of the churn prediction model used to generate this report.
↳ training_job_date string Date and time that the churn prediction model was trained.
current_churn_percentage float Current customer churn percentage.
churn_direction_indication string A human friendly indication of the direction churn percentage is moving since the last churn calculation.
churn_percentage_difference float The numerical difference in current and previous churn percentage.
features_of_importance list - objects Features, listed in descending order, by feature_importance of each feature that contributed to churn for a customer.
Example churn prediction report object: 
--


                
Retrieve Churn Prediction Report

Generate and retrieve current churn prediction report.


Parameters
None


Returns
Churn prediction report object.


CLI commands
octy-cli churn-report -f {path/to/save/churn-report/}[optional]
Retrieve churn prediction report request: 
--
GET /v1/retention/churn_prediction/report
Host: api.octy.ai
Authorization: Basic ...

RESPONSE: 
--