API Reference

Hellotext provides a powerful REST API designed for developer happiness. We make constant efforts in keeping all resources and actions simple and consistent.

All responses are formatted and returned in JSON.

API Endpoint
https://api.hellotext.com

Authentication

All requests to the API must to be authenticated. Authentication is performed by sending a token with each request to the API.

You can create and manage your authorization tokens from the business settings page. All authorizations tokens are specific to the business it was created from.

To authenticate make sure to include an authorization header with the format Authorization: Bearer {token}. Replace the token with the authorization token.

Example Request
curl https://api.hellotext.com/v1/profiles \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Errors

Hellotext uses conventional HTTP response codes to indicate status of a request. When a request is valid but does not complete as expected we return a 422 error and a errors JSON object is attached to the object including a collection of errors including type and description.

Attributes
string
A code that represents the error in string format.
string
A detailed description of the error.
string
Name of the parameter associated to the error.
HTTP status code summary
400 Bad Request
Often missing a required parameter.
401 Unauthorized
No valid API key.
404 Not Found
The requested item does not exist.
422 Request Failed
Parameters were valid but request failed.
500, 502, 503, 504 Server errors
Something went wrong.
Error types summary
object_invalid
At least one of the optional parameters must be provided.
integration_missing
You're trying to use an integration that is not enabled. Enable the integration on the Dashboard.
identity_assigned_already
Some numbers are already assigned to other subscribers.
phone_number_invalid
One or more provided phone numbers is invalid. Provide valid numbers in e164 format.
parameter_missing
One or more required parameters are not present.
parameter_not_unique
This parameter is already assigned to another object of the same type.
parameter_invalid
One or more of the passed parameters has an invalid value.
parameter_invalid_empty
One or more required parameters is empty.
ambiguous_parameter
One or more possible parameters were provided for the same role. Specify at least one of the possible values.
not_found
This object was not found. Perhaps it was deleted.
Response
{ 
  "errors": [
    {
      "type": "parameter_missing",
      "message": "One or more required parameters are not present",
      "parameter": "name"
    }
  ]
}

Pagination

All first-level collections of resources can be paginated. Collections are sorted by creation date, showing most recent objects first and limiting the results to 25 by default. To get adjust the number results you can use the limit parameter.

Given that it is assumed that new objects will be created, to keep pagination consistent you can obtain the next set of results from the last object id of the previous collection using the parameter starting_after. This includes the next set of results after (excluding) the passed id. This is also called vector pagination.

You can also achieve the opposite and retrieve all results up to the given id passing the ending_before.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
Example Request
curl -G https://api.hellotext.com/v1/profiles \
  -d starting_after="BvYeyVYz" \
  -d limit=10 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Profiles

Customers are represented as customer profiles. Each individual customer represents a unique profile object that unifies all its characteristics and history of interactions with the business.

Profiles accept any number of properties like phone numbers, emails, geo-localized addresses, personal attributes as birthday, gender or any other customized one.

Endpoints
  POST /v1/profiles
   GET /v1/profiles/:id
 PATCH /v1/profiles/:id
DELETE /v1/profiles/:id
   GET /v1/profiles

The profile object

Attributes
id
string
Unique identifier of the object.
string
Type of object. This is always profile.
array
A collection of all the emails on this profile set as properties of kind email.
string
First name of the customer represented in the profile.
string
Last name of the customer represented in the profile.
array
A collection of all the phone numbers on this profile set as properties of kind phone, listed in e164 format.
hash
Array of hashes representing properties object of the profile. For example phone numbers, Mercado Libre properties. Show child attributes Hide child attributes
id
string
Unique identifier of the object.
enum
The format of the property.
format depends on its kind
The current value set on the property for this profile.
enum
The current state of the profile that indicates if the profile is explicitly subscribed to receive promotional content or does not want to receive any promotional communication.
Possible enum values
subscribed
unconfirmed Default
unsubscribed
The profile object
{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [
    "will.e@acme.com"
  ],  
  "first_name": "Will E",
  "last_name": "Coyote",
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "value": {
        "country": "US",
        "latitude": "34.150144",
        "longitude": "-118.3467879",
        "locality": "Burbank",
        "notes": null,
        "postal_code": "91505",
        "region": "California",
        "subregion": null,
        "street": { 
          "name": "Warner Blvd",
          "number": "3400"
        }
      }
    },
    {
      "id": "MQNKalb7",
      "kind": "birthday",
      "value": {
        "day": "3",
        "month": "11",
        "year": "1985",
      }
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "value": "ACME Corporation"
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "value": "will.e@acme.com"
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "value": "male"
    },    
    {
      "id": "aXlmWN26",
      "kind": "mercadolibre",
      "value": "TESTWCWKHJQR"
    },
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "value": "+59898000001"
    },
  ],
  "state": "subscribed"
}

Property kinds

Properties have different formats for their values depending on their kind.

Each kind of property expects a specific format as its value. Please refer to the description of each one below.

Properties values are always set from the profile object.

The address property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always address.
hash
An address hash containing any of the following details. Show child attributes Hide child attributes
string
Country code in ISO 3166-1 alpha-2 format.
float
Latitude coordinates of the location.
float
Longitude coordinates of the location.
string
The locality of the address. This typically represents the neighborhood or the city name.
text
References, landmarks or indications that helps to locate the address. Useful for delivery services.
string
Postal code of the address.
string
The region of the address refers to the to biggest political administration inside the country. Depending on the country this typically is the state, province or department.
string
The subregions refers to the immediate political administration below the primary region. Depending on the country this could be the county of a state, or the department of a province.
hash
Hash that represents the street name and its number. Show child attributes Hide child attributes
string
Name of the street or route.
string
House or building number, name or reference.
The address property
{
  "id": "04lR0NYX",
  "kind": "address",
  "value": {
    "country": "US",
    "latitude": "34.150144",
    "longitude": "-118.3467879",
    "locality": "Burbank",
    "notes": null,
    "postal_code": "91505",
    "region": "California",
    "subregion": null,
    "street": { 
      "name": "Warner Blvd",
      "number": "3400"
    }
  }
}

The birthday property

The birthday property is based on the date property and it inherits its structure. It has a special birthday kind as it is specifically implemented to help keep track of customer birthdays. Using this property makes it easier to target customers by age or day of month when using Segments or Journeys.

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always birthday.
hash
This hash represents a date. It is possible to partially complete with the information at hand. For example, you can only enter the year of birth or the day and month. Show child attributes Hide child attributes
day
integer
Day of the month. Possible values are 1 to 31. Must be specified together with a month.
integer
Month of the year represented in numbers. Possible values are 1 to 12.
integer
Year represented in numeric value.
The birthday property
{
  "id": "MQNKalb7",
  "kind": "birthday",
  "value": {
    "day": 3,
    "month": 11,
    "year": 1980
  }
}

The checkbox property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always checkbox.
boolean
Expects either true or false. Defaults to false.
The checkbox property
{
  "id": "A4YaEwmd",
  "kind": "checkbox",
  "value": true
}

The company property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always company.
string
Name of the company of the profile.
The company property
{
  "id": "A4YaEwmd",
  "kind": "company",
  "value": "ACME Corporation"
}

The date property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always date.
hash
This hash represents a date. It is possible to partially complete with the information at hand. For example, you can only enter the year of birth or the day and month. Show child attributes Hide child attributes
day
integer
Day of the month. Possible values are 1 to 31. Must be specified together with a month.
integer
Month of the year represented in numbers. Possible values are 1 to 12.
integer
Year represented in numeric value.
The date property
{
  "id": "MQNKalb7",
  "kind": "date",
  "value": {
    "day": 3,
    "month": 11,
    "year": 1980
  }
}

The email property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always email.
string
Email address of the customer profile.
The email property
{
  "id": "4wNApjWo",
  "kind": "email",
  "value": "will.e@acme.com"
}

The gender property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always gender.
string
Value that represents the gender of the profile. Use male for male and female for female. Use any other value to represent other genders.
The gender property
{
  "id": "4wNApjWo",
  "kind": "gender",
  "value": "male"
}

The mercadolibre property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always mercadolibre.
string
Represents a username from Mercado Libre.
The mercadolibre property
{
  "id": "zxNY7ly2",
  "kind": "mercadolibre",
  "value": "WILLE900001"
}

The number property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always number.
float
Any numeric value as integer or decimal.
The number property
{
  "id": "JAl5zjvZ",
  "kind": "number",
  "value": 29.99
}

The phone property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always phone.
e164
Represents a phone number in e164 format.
The phone property
{
  "id": "GmjE9jXq",
  "kind": "phone",
  "value": "+59898000001"
}

The tags property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always tags.
array
Represents a collection of tags in string format.
The tags property
{
  "id": "PbNdakDE",
  "kind": "tags",
  "value": ["tag1", "tag2"]
}

The text property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always text.
text
Represents any specified text. Can be used for notes about the profile or to store any business specific metadata.
The text property
{
  "id": "wVkxoNe8",
  "kind": "text",
  "value": "Long lasting customer"
}

The url property

Attributes
id
string
Identifier of the property object.
string
The format of the property. This is always url.
string
Represents an URL.
The url property
{
  "id": "g9lDQjAp",
  "kind": "url",
  "value": "https://www.hellotext.com"
}

Create a profile

Creates a new profile.

Parameters
string
Set the email address for the default email property.
string
Set the email address for the email property with the name declared inside its brackets. For example email[work]= will set the email for the email property with name work. The property will be created for the current profile automatically if it does not exist already.
string
First name of the customer represented in the profile.
string
Last name of the customer represented in the profile.
string
Set the phone number for the default phone property. Expects a number in e164 format or otherwise a number in local format that will be converted to e164 using the business country for its country prefix.
string
Set the phone number for the phone property with the name declared inside its brackets. For example phone[work]= will set the phone for the phone property with name work. The property will be created for the current profile automatically if it does not exist already.
string
Set a property value by passing the id of the property, for example property[gVlpOkwJ]=MyValue.
string
Set a property value by passing the name of the property, for example property[MyProperty]=MyValue. If the property does not have a name, it is possible to reference it by passing its kind as its name i.e. property[gender]=male.
boolean
Set to true to subscribe the customer on profile creation. Typically this is used when already received explicit consent from the customer to receive promotional communications of your brand. The default value is false, meaning that new profiles do not become subscribed automatically.
POST /v1/profiles
curl https://api.hellotext.com/v1/profiles \
  -d first_name="Will E" \
  -d last_name=Coyote \
  -d phone=+59899000001 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/profiles
{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [],  
  "first_name": "Will E",
  "last_name": "Coyote",
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "value": {
        "country": null,
        "latitude": null,
        "longitude": null,
        "locality": null,
        "notes": null,
        "postal_code": null,
        "region": null,
        "subregion": null,
        "street": { 
          "name": null,
          "number": null
        }
      }
    },
    {
      "id": "MQNKalb7",
      "kind": "birthday",
      "value": null
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "value": null
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "value": null
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "value": null
    },    
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "value": "+59898000001"
    },
  ],
  "state": "unconfirmed"
}

Retrieve a profile

Retrieves an existing profile.

GET /v1/profiles/:id
curl -G https://api.hellotext.com/v1/profiles/MzYwlE50 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a profile

Updates the specified profile with the provided information.

Parameters
string
Set the email address for the default email property.
string
Set the email address for the email property with the name declared inside its brackets. For example email[work]= will set the email for the email property with name work. The property will be created for the current profile automatically if it does not exist already.
string
First name of the customer represented in the profile.
string
Last name of the customer represented in the profile.
string
Set the phone number for the default phone property. Expects a number in e164 format or otherwise a number in local format that will be converted to e164 using the business country for its country prefix.
string
Set the phone number for the phone property with the name declared inside its brackets. For example phone[work]= will set the phone for the phone property with name work. The property will be created for the current profile automatically if it does not exist already.
string
Set a property value by passing the id of the property, for example property[gVlpOkwJ]=MyValue.
string
Set a property value by passing the name of the property, for example property[MyProperty]=MyValue. If the property does not have a name, it is possible to reference it by passing its kind as its name i.e. property[gender]=male.
PATCH /v1/profiles/:id
curl https://api.hellotext.com/v1/profiles/MzYwlE50 \
  -d email="will.e@acme.com" \
  -d gender=male \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [
    "will.e@acme.com"
  ],  
  "first_name": "Will E",
  "last_name": "Coyote",
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "value": {
        "country": null,
        "latitude": null,
        "longitude": null,
        "locality": null,
        "notes": null,
        "postal_code": null,
        "region": null,
        "subregion": null,
        "street": { 
          "name": null,
          "number": null
        }
      }
    },
    {
      "id": "MQNKalb7",
      "kind": "birthday",
      "value": null
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "value": null
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "value": "will.e@acme.com"
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "value": "male"
    },    
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "value": "+59898000001"
    },
  ],
  "state": "unconfirmed"
}

Delete a profile

Permanently deletes the specified profile. All its associated conversations and properties will be also removed. If you want to preserve the properties and/or their messages and events you should move the existing properties to a different profile first.

DELETE /v1/profiles/:id
curl -X DELETE https://api.hellotext.com/v1/profiles/MzYwlE50 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "MzYwlE50",
  "type": "profile",
  "deleted": true
}

List all profiles

Lists existing profiles sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/profiles
curl -G https://api.hellotext.com/v1/profiles \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "profiles": [
    {
      "id": "MzYwlE50",
      "type": "profile",
      "created_at": 1665684173,
      "emails": [
        "will.e@acme.com"
      ],  
      "first_name": "Will E",
      "last_name": "Coyote",
      "phones": [
        "+59898000001"
      ],
      "properties": [
        {
          "id": "04lR0NYX",
          "kind": "address",
          "value": {
            "country": "US",
            "latitude": "34.150144",
            "longitude": "-118.3467879",
            "locality": "Burbank",
            "notes": null,
            "postal_code": "91505",
            "region": "California",
            "subregion": null,
            "street": { 
              "name": "Warner Blvd",
              "number": "3400"
            }
          }
        },
        {
          "id": "MQNKalb7",
          "kind": "birthday",
          "value": {
            "day": "3",
            "month": "11",
            "year": "1985",
          }
        },
        {
          "id": "gVlpOkwJ",
          "kind": "company",
          "value": "ACME Corporation"
        },
        {
          "id": "4wNApjWo",
          "kind": "email",
          "value": "will.e@acme.com"
        },
        {
          "id": "e0N09kB3",
          "kind": "gender",
          "value": "male"
        },    
        {
          "id": "aXlmWN26",
          "kind": "mercadolibre",
          "value": "TESTWCWKHJQR"
        },
        {
          "id": "GmjE9jXq",
          "kind": "phone",
          "value": "+59898000001"
        },
      ],
      "state": "subscribed"
    }
    {...},
    {...}
  ]
}

Subscribe a profile

Mark a profile as subscribed to receive promotional communications from your brand.

POST /v1/profiles/:id/subscribe
curl -X POST https://api.hellotext.com/v1/profiles/MzYwlE50/subscribe \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [],  
  "first_name": "Will E",
  "last_name": "Coyote",
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "value": {
        "country": null,
        "latitude": null,
        "longitude": null,
        "locality": null,
        "notes": null,
        "postal_code": null,
        "region": null,
        "subregion": null,
        "street": { 
          "name": null,
          "number": null
        }
      }
    },
    {
      "id": "MQNKalb7",
      "kind": "birthday",
      "value": null
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "value": null
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "value": null
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "value": null
    },    
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "value": "+59898000001"
    },
  ],
  "state": "subscribed"
}

Unsubscribe a profile

Unsubscribe a profile from receiving future promotional communications from your brand.

POST /v1/profiles/:id/unsubscribe
curl -X POST https://api.hellotext.com/v1/profiles/MzYwlE50/unsubscribe \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [],  
  "first_name": "Will E",
  "last_name": "Coyote",
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "value": {
        "country": null,
        "latitude": null,
        "longitude": null,
        "locality": null,
        "notes": null,
        "postal_code": null,
        "region": null,
        "subregion": null,
        "street": { 
          "name": null,
          "number": null
        }
      }
    },
    {
      "id": "MQNKalb7",
      "kind": "birthday",
      "value": null
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "value": null
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "value": null
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "value": null
    },    
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "value": "+59898000001"
    },
  ],
  "state": "unsubscribed"
}

Properties

Properties are the attributes of profiles such as phone, email, company, gender, birthday and address.

You can create custom properties for any business specific need by simply choosing its property kind. Each property kind expects a different structure for its value. For more information see the detailed breakdown below.

Once new properties are defined, they became immediately available on all new and existing profiles.

Endpoints
  POST /v1/properties
   GET /v1/properties/:id
 PATCH /v1/properties/:id
DELETE /v1/properties/:id
   GET /v1/properties

The property object

Attributes
id
string
Unique identifier of the object.
string
Type of object. This is always property.
epoch
Date of creation of the property.
enum
The format of the property.
Possible enum values
address
birthday
checkbox
company
date
email
gender
mercadolibre
number
phone
tags
text
url
string
Optional name of the property.
integer
Numeric position of the property in relation to others for sorting. New properties get the last position number if not specified. If a different position is given, existing properties will update their positions accordingly.
string
Unique identifier of the profile that this property belong to. If specified, the property becomes only available for the specified profile and will not be visible to others.
The property object
{
  "id": "OBYBnY69",  
  "type": "property",
  "kind": "text",
  "created_at": 1665684173,
  "name": "My Property",
  "position": 8,
  "profile_id": null,
}

Create a property

Creates a new property.

Parameters
enum
Required
The format of the property.
Possible enum values
address
checkbox
date
email
number
phone
tags
text
url
string
Optional name of the property.
string
Unique identifier of the profile that this property belong to. If specified, the property becomes only available for the specified profile and will not be visible to others.
POST /v1/properties
curl https://api.hellotext.com/v1/properties \
  -d profile_id=OBYBnY69 \
  -d kind=text \
  -d name="My Property" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/properties
{
  "id": "OBYBnY69",  
  "type": "property",
  "created_at": 1665684173,
  "kind": "text",
  "name": "My Property",
  "position": 8,
  "profile_id": null
}

Retrieve a property

Retrieves an existing property.

GET /v1/properties/:id
curl -G https://api.hellotext.com/v1/properties/OBYBnY69 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a property

Updates the specified property with the provided information.

Parameters
enum
Required
The format of the property.
Possible enum values
address
checkbox
date
email
number
phone
tags
text
url
string
Optional name of the property.
string
Unique identifier of the profile that this property belong to. If specified, the property becomes only available for the specified profile and will not be visible to others.
PATCH /v1/properties/:id
curl https://api.hellotext.com/v1/properties/OBYBnY69 \
  -d name="My Renamed Property" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "OBYBnY69",  
  "type": "property",
  "created_at": 1665684173,
  "kind": "text",
  "name": "My Renamed Property",
  "position": 8,
  "profile_id": null
}

Delete a property

Permanently deletes the specified property.

DELETE /v1/properties/:id
curl -X DELETE https://api.hellotext.com/v1/properties/OBYBnY69 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "OBYBnY69",
  "type": "property",
  "deleted": true
}

List all properties

Lists existing properties sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/properties
curl -G https://api.hellotext.com/v1/properties \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "properties": [
    {
      "id": "OBYBnY69",  
      "type": "property",
      "created_at": 1665684173,
      "kind": "text",
      "name": "My Property",
      "position": 8,
      "profile_id": null
    }
    {...},
    {...}
  ]
}

Coupons

Import the coupons from your eCommerce that you would like to send on your promotional campaigns. You can measure the results of the different coupons.

Endpoints
  POST /v1/coupons
   GET /v1/coupons/:id
 PATCH /v1/coupons/:id
DELETE /v1/coupons/:id
   GET /v1/coupons

The coupon object

Attributes
id
string
Unique identifier of the coupon.
string
Type of object. This is always coupon.
string
Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE.
epoch
Date of creation of the coupon.
string
Description of the coupon. This is available as a tag to be used on messages.
url
URL that redeems the coupon.
string
Name of the coupon for reference in Hellotext. This is not public.
The coupon object
{
  "id": "xJEOaPdk",
  "type": "coupon",
  "code": "SALE",
  "created_at": 1665684173,
  "description": "Get 15% off all our summer sale",
  "destination_url": "https://www.myshop.com/redeem/SALE",
  "name": "Summer SALE"
}

Create a coupon

Creates a new coupon.

Parameters
string
Required
Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE.
string
Required
Description of the coupon. This is available as a tag to be used on messages.
url
Required
URL that redeems the coupon.
string
Required
Name of the coupon for reference in Hellotext. This is not public.
POST /v1/coupons
curl https://api.hellotext.com/v1/coupons \
  -d name="Summer SALE" \
  -d code=SALE \
  -d description="Get 15% off all our summer sale" \
  -d destination_url="https://www.myshop.com/redeem/SALE" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/coupons
{
  "id": "xJEOaPdk",
  "type": "coupon",
  "code": "SALE",
  "created_at": 1665684173,
  "description": "Get 15% off all our summer sale",
  "destination_url": "https://www.myshop.com/redeem/SALE",
  "name": "Summer SALE"
}

Retrieve a coupon

Retrieves an existing coupon.

GET /v1/coupons/:id
curl -G https://api.hellotext.com/v1/coupons/xJEOaPdk \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a coupon

Updates the specified coupon with the provided information.

Parameters
string
Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE.
url
Description of the coupon. This is available as a tag to be used on messages.
url
URL that redeems the coupon.
string
Name of the coupon for reference in Hellotext. This is not public.
PATCH /v1/coupons/:id
curl https://api.hellotext.com/v1/coupons/xJEOaPdk \
  -d name="Summer SALE" \
  -d code=SALE15 \
  -d description="Get 15% off all our summer sale" \
  -d destination_url="https://www.myshop.com/redeem/SALE" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "xJEOaPdk",
  "type": "coupon",
  "code": "SALE15",
  "created_at": 1665684173,
  "description": "Get 15% off all our summer sale",
  "destination_url": "https://www.myshop.com/redeem/SALE",
  "name": "Summer SALE"
}

Delete a coupon

Permanently deletes the specified coupon.

DELETE /v1/coupons/:id
curl -X DELETE https://api.hellotext.com/v1/coupons/xJEOaPdk \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "xJEOaPdk",
  "type": "coupon",
  "deleted": true
}

List all coupons

Lists existing coupons sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/coupons
curl -G https://api.hellotext.com/v1/coupons \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "coupons": [
    {
      "id": "xJEOaPdk",
      "type": "coupon",
      "code": "SALE15",
      "created_at": 1665684173,
      "description": "Get 15% off all our summer sale",
      "destination_url": "https://www.myshop.com/redeem/SALE",
      "name": "Summer SALE"
    },
    {...},
    {...}
  ]
}

Tracking

When an event happens on your application that you wish to let Hellotext know about.

Tracked events are used to classify your subscribers according to rules on Segments.

When calling an event tracking API pass the desired name in the action parameter.

Some actions are the inverse of another action. Meaning that, when action A happens, it effectively undo Action B. Here is a list of actions and their counteractions:

  • app.installed counteractions are app.removed and vice-versa.
  • cart.added counteractions are cart.removed and vice-versa.
  • profile.subscribed counteractions are profile.unsubscribed and vice-versa.
  • order.placed, order.confirmed, and order.shipped counteractions are order.cancelled and refund.received.
  • product.purchased counteractions are refund.received.
Endpoints
  POST /v1/attribution/events

Track app events

Track important events performed by your customers when they interact with your app. Most common actions include tracking when an app is installed with action app.installed, removed with app.removed, or when a user spends a certain amount with app.spent.

When tracking events associated to sessions created after a campaign all attribution values including monetary values will be aggregated into the campaign reportings.

Parameters
string
Required
The name of the action to track. Possible values are app.spent, app.installed and app.removed.
string
Required
Unique identifier of the app object that this event is associated to.
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null. Required if action=app.spent.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD. Required if action=app.spent.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="app.installed" \
  -d app_id=xnqJQ47v \
  -d session_id=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "app.installed",
  "app_id": "xnqJQ47v",
  "amount": null,
  "created_at": 1665684173,  
  "currency": "USD",
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
}

Track cart events

Track the events performed by customers when they add or removed items from their shopping cart. Available values are cart.added for items added to the cart and cart.removed for items removed.

The monetary values associated to the cart items will be aggregated to the campaign reportings.

Parameters
string
Required
The name of the action to track. Possible values are cart.added and cart.removed.
string
Required
Unique identifier of the cart object that this event is associated to.
array
Array of identifiers of product objects that this event is associated to.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="cart.added" \
  -d cart_id=wx4Vn4no \
  -d product_ids[]=vxqQJ3Yg \
  -d session_id=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "cart.added",
  "amount": null,
  "cart_id": "wx4Vn4no",
  "created_at": 1665684173,
  "currency": "USD",
  "product_ids": [
    "vxqQJ3Yg"
  ],
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
}

Track coupon events

Track the events performed by your customers when they redeem coupons. Available value is coupon.redeemed for coupons redeemed.

The monetary values associated to the coupon redeem will be aggregated to the campaign reportings.

Parameters
string
Required
The name of the action to track. Possible value is coupon.redeemed.
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
string
Required
Description
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
array
Array of identifiers of product objects that this event is associated to.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="coupon.redeemed" \
  -d coupon_id=wx4Vn4no \
  -d session_id=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "coupon.redeemed",
  "amount": null,  
  "coupon_id": "wx4Vn4no",
  "created_at": 1665684173,
  "currency": "USD",
  "product_ids": [
    "vxqQJ3Yg"
  ],
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
}

Track form events

Track the events performed by your customers when they complete a form. Available actions are form.completed.

The monetary values associated to the form completions will be aggregated to the campaign reportings.

Parameters
string
Required
The name of the action to track. Possible value is form.completed.
string
Required
Unique identifier of the form object that this event is associated to.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="form.added" \
  -d form_id=wx4Vn4no \
  -d product_ids[]=vxqQJ3Yg \
  -d session_id=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "form.added",
  "amount": null,
  "form_id": "wx4Vn4no",
  "created_at": 1665684173,
  "currency": "USD",  
  "product_ids": [
    "vxqQJ3Yg"
  ],
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
}

Track order events

Track the events related to the lifecycle of your customer's orders. Available actions are order.placed when an order is placed by a customer, order.confirmed when is confirmed, order.cancelled if cancelled and order.shipped when shipped.

The monetary values associated to the orders will be aggregated to the campaign reportings.

Parameters
string
Required
The name of the action to track. Possible values are order.placed, order.confirmed, order.cancelled, order.shipped.
string
Required
Unique identifier of the order object that this event is associated to.
array
Array of identifiers of product objects that this event is associated to.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="order.placed" \
  -d order_id=wx4Vn4no \
  -d session_id=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "order.placed",
  "amount": null,
  "order_id": "wx4Vn4no",
  "created_at": 1665684173,
  "currency": "USD",  
  "product_ids": [],
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
}

Track product events

Track the events of purchases made by your customers. If your customers places orders, you can track the order actions instead. Available product actions are product.purchased when a customer purchases a product and product.viewed when a product is viewed from a product page.

The monetary values associated to the product purchase will be aggregated to the campaign reportings.

Parameters
string
Required
The name of the action to track. Possible values are product.purchased and product.viewed.
array
Array of identifiers of product objects that this event is associated to.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="product.purchased" \
  -d product_ids[]=vxqQJ3Yg \
  -d session_id=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "product.purchased",
  "amount": null,
  "created_at": 1665684173,
  "currency": "USD",  
  "product_ids": [
    "vxqQJ3Yg"
  ],
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
}

Track refund events

Track the events related to the refunds requested by your customers. Available actions are refund.requested and refund.received.

The monetary values associated to the refunds issued will be aggregated to the campaign reportings.

Parameters
string
Required
The name of the action to track. Possible values are refund.requested and refund.received.
string
Required
Unique identifier of the refund object that this event is associated to.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="refund.added" \
  -d refund_id=wx4Vn4no \
  -d product_ids[]=vxqQJ3Yg \
  -d session_id=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "refund.added",
  "amount": null,
  "refund_id": "wx4Vn4no",
  "created_at": 1665684173,
  "currency": "USD",  
  "product_ids": [
    "vxqQJ3Yg"
  ],
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
}

Track view events

Track the page views performed by your customers on your website or shop. Currently available action is page.visited.

The number of views will be aggregated to the campaign reportings.

Parameters
string
Required
The name of the action to track. Possible value is page.visited.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
string
Required
Unique identifier of the view object that this event is associated to.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="view.added" \
  -d session_id=2KAGgAgm \
  -d view_id=brA6VAXW \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "view.added",
  "amount": null,
  "created_at": 1665684173,
  "currency": "USD",  
  "product_ids": [
    "vxqQJ3Yg"
  ],
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
  "view_id": "brA6VAXW",
}

Track custom events

Hellotext provides a list of ready-to-use actions to track the most common customers interactions with your business such as purchases, visits to your site, products added to cart, form completions and more. However these are not always enough and sometimes you need a little more flexibility when needing to define specific actions for your business needs.

It is possible to specify any customized action name when tracking events as long as the action object has been previously created. Once the action is created you can simply use its name to track a new event.

Please keep in mind that monetary values passed to these event will be aggregated to the campaign reportings as sales.

See Actions.

Parameters
string
Required
The name of the custom action to track. The custom action must be previously created.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
POST /v1/attribution/events
curl https://api.hellotext.com/v1/attribution/events \
  -d action="signup_form.completed" \
  -d session_id=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "erA2RAXE",  
  "type": "event",
  "action": "signup_form.completed",
  "amount": null,
  "created_at": 1665684173,
  "currency": "USD",  
  "product_ids": [
    "vxqQJ3Yg"
  ],
  "session_id": "2KAGgAgm",
  "tracked_at": 1665684173,
}

Actions

Hellotext provides a basic set of actions, perfect for starting your next attribution campaign. But, when the need arises to track different actions not provided by Hellotext you can extend the set of available actions by creating your own custom actions.

You are free to name the actions any way you like. We recommend to take a dot approach when naming your actions, to have them scoped and states, for example custom actions can be like the following.

See Track custom events.

Custom action examples
subscriber.signed_up
signup_form.completed
subscriber.voted
Endpoints
  POST /v1/attribution/actions
   GET /v1/attribution/actions/:id
 PATCH /v1/attribution/actions/:id
DELETE /v1/attribution/actions/:id
   GET /v1/attribution/actions

The action object

Attributes
id
string
Unique identifier of the action object.
string
Type of object. This is always action.
epoch
Date of creation of the action object.
string
The name of the action, duplicate names are not allowed.
string
Used to display the action on Segments filters. If not provided, will be the same name of name parameter.
The action object
{
  "id": "Wvqz2qD1",  
  "type": "action",
  "created_at": 1665684173
  "name": "contact.signed_up",
  "title": "Contact Signed-Up"
}

Create an action

Creates a new action.

Parameters
string
Required
The name of the action, duplicate names are not allowed.
string
Used to display the action on Segments filters. If not provided, will be the same name of name parameter.
POST /v1/attribution/actions
curl https://api.hellotext.com/v1/attribution/actions \
  -d name="contact.signed_up" \
  -d title="Contact Signed-Up" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/attribution/actions
{
  "id": "Wvqz2qD1",  
  "type": "action",
  "created_at": 1665684173
  "name": "contact.signed_up",
  "title": "Contact Signed-Up"
}

Retrieve an action

Retrieves an existing action.

GET /v1/attribution/actions/:id
curl -G https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update an action

Updates the specified action with the provided information.

Parameters
string
The name of the action, duplicate names are not allowed.
string
Used to display the action on Segments filters. If not provided, will be the same name of name parameter.
PATCH /v1/attribution/actions/:id
curl https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
  -d name="contact.subscribed" \
  -d title="Contact Subscribed" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "Wvqz2qD1",  
  "type": "action",
  "created_at": 1665684173
  "name": "contact.subscribed",
  "title": "Contact Subscribed"
}

Delete an action

Permanently deletes the specified action.

DELETE /v1/attribution/actions/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "Wvqz2qD1",
  "type": "action",
  "deleted": true
}

List all actions

Lists existing actions sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/actions
curl -G https://api.hellotext.com/v1/attribution/actions \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "actions": [
    {
      "id": "Wvqz2qD1",  
      "type": "action",
      "created_at": 1665684173
      "name": "contact.signed_up",
      "title": "Contact Signed-Up"
    },
    {...},
    {...}
  ]
}

Apps

App objects represent the applications your own or manage that your audience interact with. For example these could be your iOS or Android apps.

You can track the events from your audience interacting with your apps. For example when someone installs an app, removes it or spends any amount.

Learn how Track app events.

Endpoints
  POST /v1/attribution/apps
   GET /v1/attribution/apps/:id
 PATCH /v1/attribution/apps/:id
DELETE /v1/attribution/apps/:id
   GET /v1/attribution/apps

The app object

Attributes
id
string
Unique identifier of the tracking event.
string
Type of object. This is always app.
epoch
Date of creation of the app object.
url
An URL of the application icon in high resolution. We will download the image and store it on our servers.
string
The name of the application. Duplicate names are not allowed.
The app object
{
  "id": "xnqJQ47v",  
  "type": "app",
  "created_at": 1665684173
  "image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
  "name": "Beauty & Care",
}

Create an app

Creates a new app.

Parameters
url
An URL of the application icon in high resolution. We will download the image and store it on our servers.
string
Required
The name of the application. Duplicate names are not allowed.
POST /v1/attribution/apps
curl https://api.hellotext.com/v1/attribution/apps \
  -d name="Beauty & Care" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/attribution/apps
{
  "id": "xnqJQ47v",  
  "type": "app",
  "created_at": 1665684173
  "image_url": null,
  "name": "Beauty & Care",
}

Retrieve an app

Retrieves an existing app.

GET /v1/attribution/apps/:id
curl -G https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update an app

Updates the specified app with the provided information.

Parameters
url
An URL of the application icon in high resolution. We will download the image and store it on our servers. Providing null will remove the attached image
string
The name of the application. Duplicate names are not allowed.
PATCH /v1/attribution/apps/:id
curl https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
  -d name="Beauty & More" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "xnqJQ47v",  
  "type": "app",
  "created_at": 1665684173
  "image_url": null,
  "name": "Beauty & More",
}

Delete an app

Permanently deletes the specified app.

DELETE /v1/attribution/apps/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "xnqJQ47v",
  "type": "app",
  "deleted": true
}

List all apps

Lists existing apps sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/apps
curl -G https://api.hellotext.com/v1/attribution/apps \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "apps": [
    {
      "id": "xnqJQ47v",  
      "type": "app",
      "created_at": 1665684173
      "image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
      "name": "Beauty & Care",
    },
    {...},
    {...}
  ]
}

Carts

Carts objects represent shopping carts objects that you can use when tracking actions such as cart.added and cart.removed.

Carts objects act as logical groups where you can group multiple products added into a cart together.

Endpoints
  POST /v1/attribution/carts
   GET /v1/attribution/carts/:id
 PATCH /v1/attribution/carts/:id
DELETE /v1/attribution/carts/:id
   GET /v1/attribution/carts

The cart object

Attributes
id
string
Unique identifier of the cart object.
string
Type of object. This is always cart.
epoch
Date of creation of the cart object.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
The cart object
{
  "id": "wx4Vn4no",  
  "type": "cart",
  "created_at": 1665684173
  "metadata": {},
}

Create a cart

Creates a new cart.

Parameters
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
POST /v1/attribution/carts
curl https://api.hellotext.com/v1/attribution/carts \
  -d metadata[attribute1]="value1" \
  -d metadata[attribute2]="value2" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/attribution/carts
{
  "id": "wx4Vn4no",  
  "type": "cart",
  "created_at": 1665684173
  "metadata": {
    "attribute1": "value1",
    "attribute2": "value2",
  },
}

Retrieve a cart

Retrieves an existing cart.

GET /v1/attribution/carts/:id
curl -G https://api.hellotext.com/v1/attribution/carts/wx4Vn4no \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a cart

Updates the specified cart with the provided information.

Parameters
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
PATCH /v1/attribution/carts/:id
curl https://api.hellotext.com/v1/attribution/carts/wx4Vn4no \
  -d name="Beauty & More" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "wx4Vn4no",  
  "type": "cart",
  "created_at": 1665684173
  "metadata": {},
}

Delete a cart

Permanently deletes the specified cart.

DELETE /v1/attribution/carts/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/carts/wx4Vn4no \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "wx4Vn4no",
  "type": "cart",
  "deleted": true
}

List all carts

Lists existing carts sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/carts
curl -G https://api.hellotext.com/v1/attribution/carts \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "carts": [
    {
      "id": "wx4Vn4no",  
      "type": "cart",
      "created_at": 1665684173
      "metadata": {},
    },
    {...},
    {...}
  ]
}

Events

Events represent the individual actions of your customers that you want to track. All events are always associated to a profile through a session_id.

An event always requires a action that you want to track. See the Tracking section for more information on the different ways to track events.

Endpoints
  POST /v1/attribution/events
   GET /v1/attribution/events/:id
 PATCH /v1/attribution/events/:id
DELETE /v1/attribution/events/:id
   GET /v1/attribution/events

The event object

Attributes
id
string
Unique identifier of the event object.
string
Type of object. This is always event.
object
The action object
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
epoch
Date of creation of the event object.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
The tracked object
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
The event object
{
  "id": "xnqJQ47v",  
  "type": "event",
  "action": {
    "id": "Wvqz2qD1",
    "type": "action",
    "created_at": 1665684173
    "name": "contact.signed_up",
    "title": "Contact Signed-Up"
  },
  "amount": 295.00,
  "created_at": 1665684173
  "currency": "USD",
  "metadata": {},
  "trackable": {
    "id": "1234",
    "type": "order",
    "amount": 295.00,
    "currency": "USD",
    "product_ids": ["xnqJQ47v"]
  },
  "tracked_at": "1665684173",
}

Retrieve an event

Retrieves an existing event.

GET /v1/attribution/events/:id
curl -G https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update an event

Updates the specified event with the provided information.

Parameters
string
Required
Description
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
string
Unique identifier of the app object that this event is associated to.
string
Unique identifier of the cart object that this event is associated to.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
string
Unique identifier of the form object that this event is associated to.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Unique identifier of the order object that this event is associated to.
string
Unique identifier of the order object that this event is associated to.
string
Unique identifier of the refund object that this event is associated to.
string
Required
Id to session object required to associate this event to. Sessions objects are meant to be used as typical sessions performed by your customers. Read Sessions for more info.
string
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
string
Unique identifier of the view object that this event is associated to.
PATCH /v1/attribution/events/:id
curl https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
  -d amount=395.00 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "xnqJQ47v",
  "type": "event",
  "action": {
    "id": "Wvqz2qD1",
    "type": "action",
    "created_at": 1665684173
    "name": "contact.signed_up",
    "title": "Contact Signed-Up"
  },
  "amount": 295.00,
  "created_at": 1665684173
  "currency": "USD",
  "metadata": {},
  "trackable": {
    "id": "1234",
    "type": "order",
    "amount": 295.00,
    "currency": "USD",
    "product_ids": ["xnqJQ47v"]
  },
  "tracked_at": "1665684173",
}

Delete an event

Permanently deletes the specified event.

DELETE /v1/attribution/events/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "xnqJQ47v",
  "type": "event",
  "deleted": true
}

List all events

Lists existing events sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/events
curl -G https://api.hellotext.com/v1/attribution/events \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "events": [
    {
      "id": "xnqJQ47v",  
      "type": "event",
      "action_name": "product.purchased",
      "amount": 295.00,
      "app_id": null,
      "cart_id": null,
      "created_at": 1665684173
      "currency": "USD",
      "form_id": null,
      "metadata": {},
      "order_id": null,
      "product_ids": [
        "vxqQJ3Yg"
      ],
      "refund_id": null,
      "session_id": "Vdqlg4nL",
      "tracked_at": "1665684173",
      "view_id": null
    },
    {...},
    {...}
  ]
}

Forms

Forms objects represent form objects that you can use when tracking actions such as form.completed.

Forms objects act as logical groups where you can group multiple actions to the same object for better reporting.

Endpoints
  POST /v1/attribution/forms
   GET /v1/attribution/forms/:id
 PATCH /v1/attribution/forms/:id
DELETE /v1/attribution/forms/:id
   GET /v1/attribution/forms

The form object

Attributes
id
string
Unique identifier of the form object.
string
Type of object. This is always form.
epoch
Date of creation of the form object.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Any name given to the form for reference. Duplicate names are not allowed.
The form object
{
  "id": "wx4Vn4no",  
  "type": "form",
  "created_at": 1665684173
  "metadata": {},
  "name": "Sign-Up Form",
}

Create a form

Creates a new form.

Parameters
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Required
Any name given to the form for reference. Duplicate names are not allowed.
POST /v1/attribution/forms
curl https://api.hellotext.com/v1/attribution/forms \
  -d name="Sign-Up Form" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/attribution/forms
{
  "id": "wx4Vn4no",  
  "type": "form",
  "created_at": 1665684173
  "metadata": {}
  "name": "Sign-Up Form",
}

Retrieve a form

Retrieves an existing form.

GET /v1/attribution/forms/:id
curl -G https://api.hellotext.com/v1/attribution/forms/wx4Vn4no \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a form

Updates the specified form with the provided information.

Parameters
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Any name given to the form for reference. Duplicate names are not allowed.
PATCH /v1/attribution/forms/:id
curl https://api.hellotext.com/v1/attribution/forms/wx4Vn4no \
  -d name="Completion Form" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "wx4Vn4no",  
  "type": "form",
  "created_at": 1665684173
  "metadata": {},
  "name": "Completion Form",
}

Delete a form

Permanently deletes the specified form.

DELETE /v1/attribution/forms/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/forms/wx4Vn4no \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "wx4Vn4no",
  "type": "form",
  "deleted": true
}

List all forms

Lists existing forms sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/forms
curl -G https://api.hellotext.com/v1/attribution/forms \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "forms": [
    {
      "id": "wx4Vn4no",  
      "type": "form",
      "created_at": 1665684173
      "metadata": {},
      "name": "Sign-Up Form",
    },
    {...},
    {...}
  ]
}

Orders

Orders objects represent orders objects that you can use to track actions through its lifecycle such as order.placed, order.confirmed, order.cancelled and order.shipped.

Order objects act as logical groups where you can group multiple actions to the same object for better reporting.

Endpoints
  POST /v1/attribution/orders
   GET /v1/attribution/orders/:id
 PATCH /v1/attribution/orders/:id
DELETE /v1/attribution/orders/:id
   GET /v1/attribution/orders

The order object

Attributes
id
string
Unique identifier of the order object.
string
Type of object. This is always order.
float
Monetary amount that represents the revenue associated to this order.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
The order object
{
  "id": "ro4a731w",  
  "type": "order",
  "amount": "199.99",
  "created_at": 1665684173
  "currency": "USD",
  "metadata": {},
}

Create an order

Creates a new order.

Parameters
float
Required
Monetary amount that represents the revenue associated to this order.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
POST /v1/attribution/orders
curl https://api.hellotext.com/v1/attribution/orders \
  -d amount=199.99 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/attribution/orders
{
  "id": "ro4a731w",  
  "type": "order",
  "amount": "199.99",
  "created_at": 1665684173
  "currency": "USD",
  "metadata": {},
}

Retrieve an order

Retrieves an existing order.

GET /v1/attribution/orders/:id
curl -G https://api.hellotext.com/v1/attribution/orders/ro4a731w \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update an order

Updates the specified order with the provided information.

Parameters
float
Monetary amount that represents the revenue associated to this order.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
PATCH /v1/attribution/orders/:id
curl https://api.hellotext.com/v1/attribution/orders/ro4a731w \
  -d metadata[state]="paid" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "ro4a731w",  
  "type": "order",
  "amount": "199.99",
  "created_at": 1665684173
  "currency": "USD",
  "metadata": {
    "state": "paid"
  },
}

Delete an order

Permanently deletes the specified order.

DELETE /v1/attribution/orders/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/orders/ro4a731w \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "ro4a731w",
  "type": "order",
  "deleted": true
}

List all orders

Lists existing orders sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/orders
curl -G https://api.hellotext.com/v1/attribution/orders \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "orders": [
    {
      "id": "ro4a731w",  
      "type": "order",
      "amount": "199.99",
      "created_at": 1665684173
      "currency": "USD",
      "metadata": {},
    },
    {...},
    {...}
  ]
}

Products

Product objects represent products that you can use to track actions through its lifecycle such as product.purchased and product.viewed.

Product objects act as logical groups where you can group multiple actions to the same object for better reporting.

Endpoints
  POST /v1/attribution/products
   GET /v1/attribution/products/:id
 PATCH /v1/attribution/products/:id
DELETE /v1/attribution/products/:id
   GET /v1/attribution/products

The product object

Attributes
id
string
Unique identifier of the product object.
string
Type of object. This is always product.
string
Name of the brand of the product.
array
A collection of categories represented as an array of strings.
string
Collection name for products that belongs to a collection.
epoch
Date of creation of the product object.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
string
An URL of the application icon in high resolution. We will download the image and store it on our servers.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Any name given to the product for reference.
float
Monetary amount that represents the revenue associated to this product.
string
A collection of tags represented as an array of strings.
The product object
{
  "id": "vxqQJ3Yg",  
  "type": "product",
  "brand": "Adidas",
  "categories": [
    "Shoes"
  ],
  "collection", "350 v2",
  "created_at": 1665684173
  "currency": "USD",
  "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
  "metadata": {},
  "name": "Yeezy Boost 350 v2",
  "price": "395.00",
  "tags": [
    "sneakers"
  ],
}

Create a product

Creates a new product.

Parameters
string
Name of the brand of the product.
array
A collection of categories represented as an array of strings.
string
Collection name for products that belongs to a collection.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
string
An URL of the application icon in high resolution. We will download the image and store it on our servers.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Required
Any name given to the product for reference.
float
Required
Monetary amount that represents the revenue associated to this product.
string
A collection of tags represented as an array of strings.
POST /v1/attribution/products
curl https://api.hellotext.com/v1/attribution/products \
  -d name="Sign-Up Form" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/attribution/products
{
  "id": "vxqQJ3Yg",  
  "type": "product",
  "brand": "Adidas",
  "categories": [
    "Shoes"
  ],
  "collection", "350 v2",
  "created_at": 1665684173
  "currency": "USD",
  "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
  "metadata": {},
  "name": "Yeezy Boost 350 v2",
  "price": "395.00",
  "tags": [
    "sneakers"
  ],
}

Retrieve a product

Retrieves an existing product.

GET /v1/attribution/products/:id
curl -G https://api.hellotext.com/v1/attribution/products/vxqQJ3Yg \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a product

Updates the specified product with the provided information.

Parameters
string
Name of the brand of the product.
array
A collection of categories represented as an array of strings.
string
Collection name for products that belongs to a collection.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
string
An URL of the application icon in high resolution. We will download the image and store it on our servers.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Any name given to the product for reference.
float
Monetary amount that represents the revenue associated to this product.
string
A collection of tags represented as an array of strings.
PATCH /v1/attribution/products/:id
curl https://api.hellotext.com/v1/attribution/products/vxqQJ3Yg \
  -d price=495.00 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "vxqQJ3Yg",  
  "type": "product",
  "brand": "Adidas",
  "categories": [
    "Shoes"
  ],
  "collection", "350 v2",
  "created_at": 1665684173
  "currency": "USD",
  "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
  "metadata": {},
  "name": "Yeezy Boost 350 v2",
  "price": "495.00",
  "tags": [
    "sneakers"
  ],
}

Delete a product

Permanently deletes the specified product.

DELETE /v1/attribution/products/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/products/vxqQJ3Yg \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "vxqQJ3Yg",
  "type": "product",
  "deleted": true
}

List all products

Lists existing products sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/products
curl -G https://api.hellotext.com/v1/attribution/products \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "products": [
    {
      "id": "vxqQJ3Yg",  
      "type": "product",
      "brand": "Adidas",
      "categories": [
        "Shoes"
      ],
      "collection", "350 v2",
      "created_at": 1665684173
      "currency": "USD",
      "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
      "metadata": {},
      "name": "Yeezy Boost 350 v2",
      "price": "395.00",
      "tags": [
        "sneakers"
      ],
    },
    {...},
    {...}
  ]
}

Refunds

Refund objects represent refunds that you can use to track actions through its lifecycle such as refund.requested and refund.received.

Refund objects act as logical groups where you can group multiple actions to the same object for better reporting.

Endpoints
  POST /v1/attribution/refunds
   GET /v1/attribution/refunds/:id
 PATCH /v1/attribution/refunds/:id
DELETE /v1/attribution/refunds/:id
   GET /v1/attribution/refunds

The refund object

Attributes
id
string
Unique identifier of the refund object.
string
Type of object. This is always refund.
float
Monetary amount that represents the revenue associated to this refund.
epoch
Date of creation of the refund object.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Id of the associated profile object that this refund belongs to.
object
The refunded object. It can be a order, product, or null
The refund object
{
  "id": "w83Pj4PY",
  "type": "refund",
  "amount": "19.90",
  "created_at": 1665684173
  "currency": "USD",
  "metadata": {},
  "profile_id": null,
  "refundable": null
}

Create a refund

Creates a new refund.

Parameters
float
Required
Monetary amount that represents the revenue associated to this refund.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Id of the associated order object that this refund belongs to.
string
Id of the associated product object that this refund belongs to.
string
Id of the associated profile object that this refund belongs to.
POST /v1/attribution/refunds
curl https://api.hellotext.com/v1/attribution/refunds \
  -d amount=19.90 \
  -d order_id=ro4a731w \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/attribution/refunds
{
  "id": "w83Pj4PY",
  "type": "refund",
  "amount": "19.90",
  "created_at": 1665684173
  "currency": "USD",
  "metadata": {},
  "profile_id": null,
  "refundable": null
}

Retrieve a refund

Retrieves an existing refund.

GET /v1/attribution/refunds/:id
curl -G https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a refund

Updates the specified refund with the provided information.

Parameters
float
Monetary amount that represents the revenue associated to this refund.
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Id of the associated order object that this refund belongs to.
string
Id of the associated product object that this refund belongs to.
string
Id of the associated profile object that this refund belongs to.
PATCH /v1/attribution/refunds/:id
curl https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
  -d amount=24.90 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "w83Pj4PY",
  "type": "refund",
  "amount": "19.90",
  "created_at": 1665684173
  "currency": "USD",
  "metadata": {},
  "profile_id": null,
  "refundable": null
}

Delete a refund

Permanently deletes the specified refund.

DELETE /v1/attribution/refunds/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "w83Pj4PY",
  "type": "refund",
  "deleted": true
}

List all refunds

Lists existing refunds sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/refunds
curl -G https://api.hellotext.com/v1/attribution/refunds \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "refunds": [
    {
      "id": "w83Pj4PY",
      "type": "refund",
      "amount": "19.90",
      "created_at": 1665684173
      "currency": "USD",
      "metadata": {},
      "profile_id": null,
      "refundable": null
    },
    {...},
    {...}
  ]
}

Sessions

A session represents a concept akin to a visitor session in the context of the browser. A session can be anonymous, i.e when the subscriber is not known.

Endpoints
  PATCH /v1/sessions/:id

Attach session

Once the subscriber becomes known. You can attach the subscriber to all events tracked with the session.

If you also want to change the session from one subscriber to another, you can pass the new subscriber in profile_id and the session will be assigned to the new subscriber.

Parameters
string
The profile to assign the session and its tracked events to.
PATCH /v1/sessions/:id
curl https://api.hellotext.com/v1/sessions/WBAkaqNz \
  -d profile_id=MzYwlE50 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "WBAkaqNz",  
  "type": "session",
  "profile_id": "MzYwlE50",
  "created_at": 1665684173,
}

Views

View objects represent page views that you can use to track actions such as page.viewed.

Views objects act as logical groups where you can group multiple actions to the same object for better reporting.

Endpoints
  POST /v1/attribution/views
   GET /v1/attribution/views/:id
 PATCH /v1/attribution/views/:id
DELETE /v1/attribution/views/:id
   GET /v1/attribution/views

The view object

Attributes
id
string
Unique identifier of the view object.
string
Type of object. This is always view.
epoch
Date of creation of the view object.
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Path of the view. If the path is not provided it will be created automatically from the URL.
string
The page title of the url or path
url
string
URL address of the view.
The view object
{
  "id": "brA6VAXW",  
  "type": "view",
  "created_at": 1665684173
  "metadata": {},
  "path": "/product",
  "title": "Products - Hellotext",
  "url": "https://www.hellotext.com/product"
}

Create a view

Creates a new view.

At least one of title, url, or path must be present.

Parameters
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Path of the view. If the path is not provided it will be created automatically from the URL.
string
The page title of the url or path
url
string
URL address of the view.
POST /v1/attribution/views
curl https://api.hellotext.com/v1/attribution/views \
  -d title="Products - Hellotext" \
  -d url="https://www.hellotext.com/product" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
POST /v1/attribution/views
{
  "id": "brA6VAXW",  
  "type": "view",
  "created_at": 1665684173
  "metadata": {},
  "path": "/product",
  "title": "Products - Hellotext",
  "url": "https://www.hellotext.com/product"
}

Retrieve a view

Retrieves an existing view.

GET /v1/attribution/views/:id
curl -G https://api.hellotext.com/v1/attribution/views/brA6VAXW \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a view

Updates the specified view with the provided information.

At least one of title, url, or path must be present.

Parameters
hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
string
Path of the view. If the path is not provided it will be created automatically from the URL.
string
The page title of the url or path
url
string
URL address of the view.
PATCH /v1/attribution/views/:id
curl https://api.hellotext.com/v1/attribution/views/brA6VAXW \
  -d metadata[attribute1]="value1" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "brA6VAXW",  
  "type": "view",
  "created_at": 1665684173
  "metadata": {
    "attribute1": "value1"
  },
  "path": "/product",
  "title": "Products - Hellotext",
  "url": "https://www.hellotext.com/product"
}

Delete a view

Permanently deletes the specified view.

DELETE /v1/attribution/views/:id
curl -X DELETE https://api.hellotext.com/v1/attribution/views/brA6VAXW \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "id": "brA6VAXW",
  "type": "view",
  "deleted": true
}

List all views

Lists existing views sorting by most recent ones. Pagination parameters are available in lists.

Parameters
string
Display results listed after (older) than the given id.
string
Display results listed before (more recent) than the given id.
integer
Limit how many results to show. Default is 25. Maximum is 100.
GET /v1/attribution/views
curl -G https://api.hellotext.com/v1/attribution/views \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Response
{
  "views": [
    {
      "id": "brA6VAXW",  
      "type": "view",
      "created_at": 1665684173
      "metadata": {},
      "path": "/product",
      "title": "Products - Hellotext",
      "url": "https://www.hellotext.com/product"
    },
    {...},
    {...}
  ]
}