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.

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.

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

type

string

A code that represents the error in string format.

message

string

A detailed description of the error.

parameter

string

Name of the parameter associated to the error.

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.

ambiguous_parameter

One or more possible parameters were provided for the same role. Specify at least one of the possible values.

identity_assigned

You are trying to assign an identity that already is present on the profile.

integration_missing

You're trying to use an integration that is not enabled. Enable the integration on the Dashboard.

not_found

This object was not found. Perhaps it was deleted.

object_invalid

At least one of the optional parameters must be provided.

parameter_invalid

This parameter has an invalid value. Consult the docs for accepted values

parameter_invalid_empty

This required parameter has an empty value. Provide a valid value for the parameter.

parameter_missing

This parameter is required.

parameter_not_unique

The value must be unique and it is already present in another object of the same type.

session_assigned_to_another_profile

This session has been assigned to another profile. It cannot be used to track events for the current profile.

undefined_property

You tried to set a property on a profile that did not exist.

{
  "errors": [
    {
      "type": "parameter_missing",
      "message": "This parameter is required.",
      "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

starting_after

string

Display results listed after (older) than the given id.

ending_before

string

Display results listed before (more recent) than the given id.

limit

integer

Limit how many results to show. Default is 25. Maximum is 100.

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.

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

The profile object

Attributes

string

Unique identifier of the object.

type

string

Type of object. This is always profile.

blocked

boolean

Has this profile been blocked or not. It is true or false

emails

array

A collection of all the emails on this profile set as properties of kind email.

first_name

string

First name of the customer represented in the profile.

last_name

string

Last name of the customer represented in the profile.

lists

array

A collection of all the lists this profile is part of.

Show child attributes

phones

array

A collection of all the phone numbers on this profile set as properties of kind phone, listed in e164 format.

properties

array

Array of hashes representing properties object of the profile. For example phone numbers, Mercado Libre properties.

Show child attributes

state

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

{
  "id": "MzYwlE50",
  "type": "profile",
  "blocked": false,
  "created_at": 1665684173,
  "emails": [
    "will.e@acme.com"
  ],
  "first_name": "Will E",
  "last_name": "Coyote",
  "lists": [
    {
      "id": "zN4Xx4Km",
      "type": "list",
      "created_at": 1665684173,
      "name": "Loyal Customers"
    }
  ],
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "name": null,
      "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",
      "name": null,
      "value": {
        "day": "3",
        "month": "11",
        "year": "1985",
      }
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "name": null,
      "value": "ACME Corporation"
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "name": null,
      "value": "will.e@acme.com"
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "name": null,
      "value": "male"
    },
    {
      "id": "aXlmWN26",
      "kind": "mercadolibre",
      "name": null,
      "value": "TESTWCWKHJQR"
    },
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "name": null,
      "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

Represents an address associated to a profile. It can help to keep track of customer's addresses. Using this property makes it easier to target customers in specific regions, streets or countries.

Attributes

string

Identifier of the property object.

kind

string

The format of the property, this is always address.

value

hash

An object that contains the address information.

Show child attributes

city

string

Required

The city of the address. Required when the street.name is empty and the suggest parameter has not been provided.

country

string

ISO 3166 alpha-2 country code of the address. Defaults to the country of the business.

latitude

string

The latitude of the address.

longitude

string

The longitude of the address.

notes

string

Additional information about the address.

postal_code

string

The postal code of the address.

region

string

The top-level administrative division within the country, typically a state or province.

street

hash

A hash that contains the street information.

Show child attributes

subregion

string

The second-level administrative division within the country, often a county or district.

suggest

string

Useful when creating or updating a profile. Instead of providing the required attributes, specifying the suggested address, for example, passing Luis A Herrara 1246, Montevideo, UY automatically fills the required attributes.

{
  "id": "MQNKalb7",
  "kind": "address",
  "name": null,
  "value": {
    "city": "Montevideo",
    "country": "UY",
    "latitude": "-0.349044168e2",
    "longitude": "-0.561370421e2",
    "notes": null,
    "postal_code": "11300",
    "region": "Departamento de Montevideo",
    "street": {
      "name": "Av. Luis Alberto de Herrera",
      "number": "1248"
    },
    "subregion": "CH",
  }
}

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

string

Identifier of the property object.

kind

string

The format of the property. This is always birthday.

value

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

{
  "id": "MQNKalb7",
  "kind": "birthday",
  "name": null,
  "value": {
    "day": 3,
    "month": 11,
    "year": 1980
  }
}

The checkbox property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always checkbox.

value

boolean

Expects either true or false. Defaults to false.

{
  "id": "A4YaEwmd",
  "kind": "checkbox",
  "name": null,
  "value": true
}

The company property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always company.

value

string

Name of the company of the profile.

{
  "id": "A4YaEwmd",
  "kind": "company",
  "name": null,
  "value": "ACME Corporation"
}

The date property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always date.

value

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

{
  "id": "MQNKalb7",
  "kind": "date",
  "name": null,
  "value": {
    "day": 3,
    "month": 11,
    "year": 1980
  }
}

The email property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always email.

value

string

Email address of the customer profile.

{
  "id": "4wNApjWo",
  "kind": "email",
  "name": null,
  "value": "will.e@acme.com"
}

The gender property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always gender.

value

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.

{
  "id": "4wNApjWo",
  "kind": "gender",
  "name": null,
  "value": "male"
}

The mercadolibre property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always mercadolibre.

value

string

Represents a username from Mercado Libre.

{
  "id": "zxNY7ly2",
  "kind": "mercadolibre",
  "name": null,
  "value": "WILLE900001"
}

The number property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always number.

value

float

Any numeric value as integer or decimal.

{
  "id": "JAl5zjvZ",
  "kind": "number",
  "name": null,
  "value": 29.99
}

The phone property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always phone.

value

e164

Represents a phone number in e164 format.

{
  "id": "GmjE9jXq",
  "kind": "phone",
  "name": null,
  "value": "+59898000001"
}

The tags property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always tags.

value

array

Represents a collection of tags in string format.

{
  "id": "PbNdakDE",
  "kind": "tags",
  "name": null,
  "value": ["tag1", "tag2"]
}

The text property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always text.

value

text

Represents any specified text. Can be used for notes about the profile or to store any business specific metadata.

{
  "id": "wVkxoNe8",
  "kind": "text",
  "name": null,
  "value": "Long lasting customer"
}

The url property

Attributes

string

Identifier of the property object.

kind

string

The format of the property. This is always url.

value

string

Represents an URL.

{
  "id": "g9lDQjAp",
  "kind": "url",
  "name": null,
  "value": "https://www.hellotext.com"
}

Create a profile

Creates a new profile.

Parameters

address

hash

string

Set the email address for the default email property.

email[name]

string

first_name

string

The first name of the profile

last_name

string

The last name of the profile

lists

array

A collection of list names that this profile will be added to. New lists will be created if a list does not exist.

Show child attributes

phone

string

phone[name]

string

property[name]

string

Set a property value by passing the property's name, for example property[Active]=true. If the property does not have a name, it's possible to target it by it's kind, i.e property[gender]=male.

property_by_id[id]

string

Set a property value by passing the id of the property, for example property_by_id[gVlpOkwJ]=MyValue.

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.

curl https://api.hellotext.com/v1/profiles \
  -d first_name="Will E" \
  -d last_name=Coyote \
  -d phone=+59899000001 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "MzYwlE50"
}

Retrieve a profile

Retrieves an existing profile.

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

address

hash

Set the address for the default address property. You can pass an address object, or optionally provide a string as address[suggest]. When providing the suggestion string, we will deconstruct the string and construct an address object from it. Providing an empty value removes the default address from the profile. For example, address='' or address={}.

string

Set the email address for the default email property. Passing an empty value will remove the default email, for example email='' will remove the default email. If the Profile has other emails, the second email will be marked as the new default.

email[id]

string

Set an email property value by passing the id of the property, for example email[gVlpOkwJ]=will.e@acme.com. Passing an empty value will remove the email from the profile. For example, email[gVlpOkwJ]='' will remove the email with the given id.

email[name]

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. Passing an empty value removes the email from the profile. For example, email[work]='' will remove the email work of the profile.

first_name

string

The first name of the profile

last_name

string

The last name of the profile

lists

array

A collection of all list names that this profile will be added to. Passing an empty array [] will remove the profile from every list.

Show child attributes

new_email

string

New default profile email. If present, it will replace the default email and become the new default. Without removing the old default email.

new_phone

string

New default profile phone. If present, it will replace the default phone number and become the new default. Without removing the old default number.

phone

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. Passing an empty value will remove the default phone from the profile. For example, phone='' will remove the default phone of the Profile. If the profile has any other phone numbers, the second phone number is marked as the new default.

phone[id]

string

Set a phone property value by passing the id of the property, for example phone[gVlpOkwJ]=099888888. Passing an empty value will remove the phone from the profile. For example, phone[gVlpOkwJ]='' will remove the phone with the given id.

phone[name]

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. Passing an empty value will remove the phone from the profile if it exists. For example, phone[work]='' will remove the phone work of the profile.

property[name]

string

Set a property value by passing the property's name, for example property[Active]=true. If the property does not have a name, it's possible to target it by it's kind, i.e property[gender]=male.

property_by_id[id]

string

Set a property value by passing the id of the property, for example property_by_id[gVlpOkwJ]=MyValue.

curl https://api.hellotext.com/v1/profiles/MzYwlE50 \
  -d email="will.e@acme.com" \
  -d gender=male \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "MzYwlE50",
  "updated": "true"
}

Delete a profile

Clears the specified profile. Clearing a profile means that all of it's properties will be removed. The associated conversations will be preserved. You can restore the profile once more through the dashboard or the API by changing the subscription state of the profile to subscribed.

curl -X DELETE https://api.hellotext.com/v1/profiles/MzYwlE50 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "MzYwlE50",
  "type": "profile",
  "deleted": true
}

List all profiles

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

Parameters

starting_after

string

Display results listed after (older) than the given id.

ending_before

string

Display results listed before (more recent) than the given id.

limit

integer

Limit how many results to show. Default is 25. Maximum is 100.

string

Limit result to profiles who have the specified email.

first_name

string

Limit results to profiles who have the specified first name.

last_name

string

Limit results to profiles who have the specified last name.

phone

string

Limit result to profiles who have the specified phone.

property[name]

string

Limit results to profiles who have the specified property value

curl -G https://api.hellotext.com/v1/profiles \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "profiles": [
    {
      "id": "MzYwlE50",
      "type": "profile",
      "created_at": 1665684173,
      "emails": [
        "will.e@acme.com"
      ],
      "first_name": "Will E",
      "last_name": "Coyote",
      "lists": [
        {
          "id": "zN4Xx4Km",
          "type": "list",
          "created_at": 1665684173,
          "name": "Loyal Customers"
        }
      ],
      "phones": [
        "+59898000001"
      ],
      "properties": [
        {
          "id": "04lR0NYX",
          "kind": "address",
          "name": null,
          "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",
          "name": null,
          "value": {
            "day": "3",
            "month": "11",
            "year": "1985",
          }
        },
        {
          "id": "gVlpOkwJ",
          "kind": "company",
          "name": null,
          "value": "ACME Corporation"
        },
        {
          "id": "4wNApjWo",
          "kind": "email",
          "name": null,
          "value": "will.e@acme.com"
        },
        {
          "id": "e0N09kB3",
          "kind": "gender",
          "name": null,
          "value": "male"
        },
        {
          "id": "aXlmWN26",
          "kind": "mercadolibre",
          "name": null,
          "value": "TESTWCWKHJQR"
        },
        {
          "id": "GmjE9jXq",
          "kind": "phone",
          "name": null,
          "value": "+59898000001"
        },
      ],
      "state": "subscribed"
    }
    {...},
    {...}
  ]
}

Subscribe a profile

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

curl -X POST https://api.hellotext.com/v1/profiles/MzYwlE50/subscribe \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [],
  "first_name": "Will E",
  "last_name": "Coyote",
  "lists": [
    {
      "id": "zN4Xx4Km",
      "type": "list",
      "created_at": 1665684173,
      "name": "Loyal Customers"
    }
  ],
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "name": null,
      "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",
      "name": null,
      "value": null
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "name": null,
      "value": null
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "name": null,
      "value": null
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "name": null,
      "value": null
    },
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "name": null,
      "value": "+59898000001"
    },
  ],
  "state": "subscribed"
}

Unsubscribe a profile

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

curl -X POST https://api.hellotext.com/v1/profiles/MzYwlE50/unsubscribe \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [],
  "first_name": "Will E",
  "last_name": "Coyote",
  "lists": [
    {
      "id": "zN4Xx4Km",
      "type": "list",
      "created_at": 1665684173,
      "name": "Loyal Customers"
    }
  ],
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "name": null,
      "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",
      "name": null,
      "value": null
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "name": null,
      "value": null
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "name": null,
      "value": null
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "name": null,
      "value": null
    },
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "name": null,
      "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.

phone, email, mercadolibre properties are grouped together and shown before all other properties, in mentioned order. Thus, their position reflects only the ordering inside their own kind.

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

The property object

Attributes

string

Unique identifier of the object.

type

string

Type of object. This is always property.

created_at

epoch

Date of creation of the property.

kind

string

The format of the property.

name

string

Optional name of the property. Duplicate names are not allowed

position

integer

Numeric position of the property in relation to others for sorting.

profile

string

Unique identifier of the profile that this property belong to.

{
  "id": "OBYBnY69",
  "type": "property",
  "created_at": 1665684173,
  "kind": "text",
  "name": "My Property",
  "position": 8,
  "profile": null,
}

Create a property

Creates a new property.

Parameters

kind

enum

Required

The format of the property.

Possible enum values

checkbox

date

email

number

phone

tags

text

url

name

string

The name of the property

position

integer

Numeric position of the property in relation to others for sorting.

profile

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. It can only be assigned to phone or email. Required when the property kind is phone or email.

curl https://api.hellotext.com/v1/properties \
  -d profile=OBYBnY69 \
  -d kind=text \
  -d name="My Property" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "OBYBnY69",
  "type": "property",
  "created_at": 1665684173,
  "kind": "text",
  "name": "My Property",
  "position": 8,
  "profile": null
}

Retrieve a property

Retrieves an existing property.

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

name

string

The name of the property

position

integer

Numeric position of the property in relation to others for sorting.

curl https://api.hellotext.com/v1/properties/OBYBnY69 \
  -d name="My Renamed Property" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "OBYBnY69",
  "type": "property",
  "created_at": 1665684173,
  "kind": "text",
  "name": "My Renamed Property",
  "position": 8,
  "profile": null
}

Delete a property

Permanently deletes the specified property.

List all properties

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

Parameters

starting_after

string

Display results listed after (older) than the given id.

ending_before

string

Display results listed before (more recent) than the given id.

limit

integer

Limit how many results to show. Default is 25. Maximum is 100.

profile

string

Unique identifier of the profile

curl -G https://api.hellotext.com/v1/properties \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "properties": [
    {
      "id": "OBYBnY69",
      "type": "property",
      "created_at": 1665684173,
      "kind": "text",
      "name": "My Property",
      "position": 8,
      "profile": null
    }
    {...},
    {...}
  ]
}

Lists

Lists act as logical grouping of profiles.

  POST /v1/lists
   GET /v1/lists/:id
 PATCH /v1/lists/:id
DELETE /v1/lists/:id
   GET /v1/lists

The list object

Attributes

string

Unique identifier of the list object.

type

string

Type of object. This is always list.

created_at

epoch

Date of creation of the list object.

name

string

Name of the list, case-sensitive. Duplicate names are not allowed

{
  "id": "zN4Xx4Km",
  "type": "list",
  "created_at": 1665684173,
  "name": "Greens",
}

Create a list

Creates a new list.

Parameters

name

string

Required

Name of the list, case-sensitive. Duplicate names are not allowed

curl https://api.hellotext.com/v1/lists \
  -d name='Beauty & Care' \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "zN4Xx4Km",
  "type": "list",
  "created_at": 1665684173,
  "name": "Beauty & Care",
}

Retrieve a list

Retrieves an existing list

curl https://api.hellotext.com/v1/lists/zN4Xx4Km \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a list

Updates a list

Parameters

name

string

Required

Name of the list, case-sensitive. Duplicate names are not allowed

curl https://api.hellotext.com/v1/lists/zN4Xx4Km \
  -d name="Loyal customers" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "zN4Xx4Km",
  "type": "list",
  "created_at": 1665684173,
  "name": "Loyal customers",
}

Delete a list

Deletes a list. Profiles in the list will not be deleted.

curl https://api.hellotext.com/v1/lists/zN4Xx4Km \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "zN4Xx4Km",
  "type": "list",
  "deleted": true
}

List all lists

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

Parameters

string

Display lists whose name start with the provided value

starting_after

string

Display results listed after (older) than the given id.

ending_before

string

Display results listed before (more recent) than the given id.

limit

integer

Limit how many results to show. Default is 25. Maximum is 100.

curl -G https://api.hellotext.com/v1/lists \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "lists": [
    {
      "id": "zN4Xx4Km",
      "type": "list",
      "created_at": 1665684173,
      "name": "Greens"
    },
    {...},
    {...}
  ]
}

Add a profile to a list

curl -X POST https://api.hellotext.com/v1/lists/dWJ8VYmz/profiles/MzYwlE50 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [],
  "first_name": "Will E",
  "last_name": "Coyote",
  "lists": [
    {
      "id": "dWJ8VYmz",
      "type": "list",
      "created_at": 1665684173,
      "name": "Loyal Customers"
    }
  ],
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "name": null,
      "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",
      "name": null,
      "value": null
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "name": null,
      "value": null
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "name": null,
      "value": null
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "name": null,
      "value": null
    },
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "name": null,
      "value": "+59898000001"
    },
  ],
  "state": "unsubscribed"
}

Remove a profile from a list

curl -X DELETE https://api.hellotext.com/v1/lists/dWJ8VYmz/profiles/MzYwlE50 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "MzYwlE50",
  "type": "profile",
  "created_at": 1665684173,
  "emails": [],
  "first_name": "Will E",
  "last_name": "Coyote",
  "lists": [],
  "phones": [
    "+59898000001"
  ],
  "properties": [
    {
      "id": "04lR0NYX",
      "kind": "address",
      "name": null,
      "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",
      "name": null,
      "value": null
    },
    {
      "id": "gVlpOkwJ",
      "kind": "company",
      "name": null,
      "value": null
    },
    {
      "id": "4wNApjWo",
      "kind": "email",
      "name": null,
      "value": null
    },
    {
      "id": "e0N09kB3",
      "kind": "gender",
      "name": null,
      "value": null
    },
    {
      "id": "GmjE9jXq",
      "kind": "phone",
      "name": null,
      "value": "+59898000001"
    },
  ],
  "state": "unsubscribed"
}

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.

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

The coupon object

Attributes

string

Unique identifier of the coupon.

type

string

Type of object. This is always coupon.

code

string

Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE.

created_at

epoch

Date of creation of the coupon.

description

string

Description of the coupon. This is available as a tag to be used on messages.

destination_url

url

URL that redeems the coupon.

reference

string

The coupon number or original identifier from the external source that created the coupon.

{
  "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",
  "reference": null,
}

Create a coupon

Creates a new coupon.

Parameters

code

string

Required

Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE. Case-sensitive. Duplicate names are not allowed.

description

string

Required

Description of the coupon. This is available as a tag to be used on messages.

destination_url

url

Required

URL that redeems the coupon.

reference

string

The coupon number or original identifier from the external source that created the coupon.

curl https://api.hellotext.com/v1/coupons \
  -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..."

{
  "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",
  "reference": null,
}

Retrieve a coupon

Retrieves an existing coupon.

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

code

string

Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE. Case-sensitive. Duplicate names are not allowed.

description

string

Description of the coupon. This is available as a tag to be used on messages.

destination_url

url

URL that redeems the coupon.

reference

string

The coupon number or original identifier from the external source that created the coupon.

curl https://api.hellotext.com/v1/coupons/xJEOaPdk \
  -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..."

{
  "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",
  "reference": null,
}

Delete a coupon

Permanently deletes the specified coupon.

curl -X DELETE https://api.hellotext.com/v1/coupons/xJEOaPdk \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xJEOaPdk",
  "type": "coupon",
  "deleted": true
}

List all coupons

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

Parameters

starting_after

string

Display results listed after (older) than the given id.

ending_before

string

Display results listed before (more recent) than the given id.

limit

integer

Limit how many results to show. Default is 25. Maximum is 100.

curl -G https://api.hellotext.com/v1/coupons \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "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",
      "reference": null,
    },
    {...},
    {...}
  ]
}

Tracking

Tracking customers interactions unlock new marketing possibilities and give businesses a complete view of the history of each customer.

By tracking customer actions it is possible to build segmented audiences based on what they do and like and use this for highly precision marketing. Businesses can trigger automations based on customer activity and give their team a head start finding opportunities to actively engage with them to sell more.

A minimal setup to track a customer event is to set the action parameter to any of the built-in actions or a custom-defined action (see Actions) and the parameter profile that represents the customer profile or the session if tracking events from campaigns or journeys short links (see Sessions).

When providing both session and profile parameters, ensure that the session is assigned to the profile. Sessions assigned to a profile cannot be used to track events for another profile. If the session is not assigned to any profile, it will be automatically assigned to the profile you pass when tracking an event.

When providing a currency. The amount must be specified. If none are provided, the values will be inherited from the trackable if the object has the attributes.

  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

action

enum

Required

The name of the action to track.

Possible enum values

app.installed

app.removed

app.spent

amount

float

Monetary amount that represents the revenue associated to this tracked event. Default value is null. Required if action=app.spent.

app

string

Required

Unique identifier of the app object associated to this event.

app_parameters

hash

A hash the can be passed instead of app parameter. The app will be created and have the event tracked for

Show child attributes

currency

Currency for the amount given in ISO 4217 format. Default value is always USD. Required if action=app.spent.

metadata

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.

profile

string

Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.

session

string

Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.

tracked_at

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.

url

The url of the page this event occurred at.

curl https://api.hellotext.com/v1/attribution/events \
  -d action="app.installed" \
  -d app=xnqJQ47v \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Track cart events

Track the events performed by customers when they add or remove items from their shopping cart. Or abandoning the cart

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

Parameters

action

enum

Required

A hash that represents the action object.

Possible enum values

cart.abandoned

cart.added

cart.removed

amount

float

Monetary amount that represents the revenue associated to this tracked event. Default value is null.

cart

string

The identifier of the cart object. Required when action is cart.abandoned.

currency

Currency for the amount given in ISO 4217 format. Default value is always USD.

metadata

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.

products

string

An array of product identifiers or product_parameter. Required when action is cart.added or cart.removed. When Cart is not given, a Cart object will be created automatically and the products are added to it. When Cart is given, the products will be added to the Cart. And the products will be displayed in the Activity Trail of the Profile.

profile

string

session

string

tracked_at

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.

url

The url of the page this event occurred at.

curl https://api.hellotext.com/v1/attribution/events \
  -d action="cart.added" \
  -d app=xnqJQ47v \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

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

action

enum

Required

The name of the action to track.

Possible enum values

coupon.redeemed

amount

float

Monetary amount that represents the revenue associated to this tracked event. Default value is null.

coupon

string

Required

Unique identifier of the coupon object associated to this event.

coupon_parameters

hash

A hash the can be passed instead of coupon parameter. The coupon will be created and have the event tracked for.

Show child attributes

currency

Currency for the amount given in ISO 4217 format. Default value is always USD.

metadata

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.

profile

string

session

string

tracked_at

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.

url

The url of the page this event occurred at.

curl https://api.hellotext.com/v1/attribution/events \
  -d action="coupon.redeemed" \
  -d coupon=wx4Vn4no \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

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

action

enum

Required

The name of the action to track.

Possible enum values

form.completed

amount

float

Monetary amount that represents the revenue associated to this tracked event. Default value is null.

currency

Currency for the amount given in ISO 4217 format. Default value is always USD.

form

string

Required

Unique identifier of the form object associated to this event.

form_parameters

hash

A hash the can be passed instead of form parameter. The form will be created and have the event tracked for.

Show child attributes

metadata

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.

profile

string

session

string

tracked_at

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.

url

The url of the page this event occurred at.

curl https://api.hellotext.com/v1/attribution/events \
  -d action="form.completed" \
  -d form=wx4Vn4no \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

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

action

enum

Required

The name of the action to track.

Possible enum values

order.cancelled

order.confirmed

order.delivered

order.placed

order.shipped

amount

float

Monetary amount that represents the revenue associated to this tracked event. Default value is null.

currency

Currency for the amount given in ISO 4217 format. Default value is always USD.

metadata

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.

order

string

Required

Unique identifier of the order object associated to this event.

order_parameters

hash

A hash the can be passed instead of order parameter. The order will be created and have the event tracked for.

Show child attributes

profile

string

session

string

tracked_at

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.

url

The url of the page this event occurred at.

curl https://api.hellotext.com/v1/attribution/events \
  -d action="order.placed" \
  -d order=wx4Vn4no \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

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. You can also track a product being added to the cart via cart.added or cart.removed when a product is removed from the cart.

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

Parameters

action

enum

Required

The name of the action to track.

Possible enum values

product.purchased

product.viewed

amount

float

Monetary amount that represents the revenue associated to this tracked event. Default value is null.

currency

Currency for the amount given in ISO 4217 format. Default value is always USD.

metadata

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.

product

string

Required

Unique identifier of the product object associated to this event.

product_parameters

hash

A hash the can be passed instead of product parameter. The product will be created and have the event tracked for.

Show child attributes

brand

string

Translation missing: en.documentation.track.event.product.attributes.product_parameters.brand.description

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

action

enum

Required

The name of the action to track.

Possible enum values

refund.received

refund.requested

amount

float

Monetary amount that represents the revenue associated to this tracked event. Default value is null.

currency

Currency for the amount given in ISO 4217 format. Default value is always USD.

metadata

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.

profile

string

refund

string

Required

Unique identifier of the refund object associated to this event.

refund_parameters

hash

A hash the can be passed instead of refund parameter. The refund will be created and have the event tracked for.

Show child attributes

session

string

tracked_at

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.

url

The url of the page this event occurred at.

curl https://api.hellotext.com/v1/attribution/events \
  -d action="refund.added" \
  -d refund=wx4Vn4no \
  -d product=vxqQJ3Yg \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

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

action

string

Required

The name of the custom action to track. The custom action must be previously created.

amount

float

Monetary amount that represents the revenue associated to this tracked event. Default value is null.

app

string

Unique identifier of the app object associated to this event.

coupon

string

Unique identifier of the app object associated to this event.

currency

Currency for the amount given in ISO 4217 format. Default value is always USD.

form

string

Unique identifier of the form object associated to this event.

metadata

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.

order

string

Unique identifier of the order object associated to this event.

product

string

Unique identifier of the product object associated to this event.

profile

string

refund

string

Unique identifier of the refund object associated to this event.

session

string

tracked_at

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.

url

The url of the page this event occurred at.

curl https://api.hellotext.com/v1/attribution/events \
  -d action="signup_form.completed" \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

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

  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

string

Unique identifier of the action object.

type

string

Type of object. This is always action.

created_at

epoch

Date of creation of the action object.

goal

boolean

Is this action used as a metric for KPIs?. Defaults to false. Setting it to true will allow events with this action to be used as a metric for KPIs displayed in the Campaigns and Journeys.

name

string

The name of the action. This is the name used in the action parameter when tracking an event. Duplicate names are not allowed.

passive

boolean

Is this action passive or not?. Defaults to true.

Passive events are events that don't affect the order of conversations in the inbox, when a passive event is recorded, the conversation's position is not changed. Passive events are not displayed on the Inbox, they are only displayed in the Activity Trail of a Profile.

Non-passive events are events that affect the order of conversations in the inbox, when an active event is recorded, the conversation's position is updated and is moved to the top so it can be handled. Non-passive events are recorded in the Inbox and the Activity Trail.

Generally, if the action is important(requires an action by your team) and you want to easily see it in the Inbox when it happens, set this attribute as false. However, if the action is not important, you can mark it as passive.

title

string

Human-friendly alternative name used on Segments and Journeys. If not provided, it will be the same as the name parameter.

{
  "id": "Wvqz2qD1",
  "type": "action",
  "created_at": 1665684173,
  "goal": false,
  "name": "signup_form.completed",
  "passive": "true",
  "title": "Signup-form completed"
}

Create an action

Creates a new action.

Parameters

goal

boolean

Is this action used as a metric for KPIs?. Defaults to false. Setting it to true will allow events with this action to be used as a metric for KPIs displayed in the Campaigns and Journeys.

name

string

Required

The name of the action. This is the name used in the action parameter when tracking an event. Duplicate names are not allowed.

passive

boolean

Is this action passive or not? Defaults to true

title

string

Human-friendly alternative name used on Segments and Journeys. If not provided, it will be the same as the name parameter.

curl https://api.hellotext.com/v1/attribution/actions \
  -d name="signup_form.completed" \
  -d title="Signup-form completed" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "Wvqz2qD1",
  "type": "action",
  "created_at": 1665684173,
  "goal": false,
  "name": "signup_form.completed",
  "passive": "true",
  "title": "Signup-form completed"
}

Retrieve an action

Retrieves an existing action.

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

goal

boolean

Is this action used as a metric for KPIs?. Defaults to false. Setting it to true will allow events with this action to be used as a metric for KPIs displayed in the Campaigns and Journeys.

name

string

Required

The name of the action. This is the name used in the action parameter when tracking an event. Duplicate names are not allowed.

passive

boolean

Is this action passive or not? Defaults to true

title

string

Human-friendly alternative name used on Segments and Journeys. If not provided, it will be the same as the name parameter.

curl https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
  -d name="contact.subscribed" \
  -d title="Contact Subscribed" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "Wvqz2qD1",
  "type": "action",
  "created_at": 1665684173,
  "goal": false,
  "name": "contact.subscribed",
  "passive": "true",
  "title": "Contact Subscribed"
}

Delete an action

Permanently deletes the specified action.

curl -X DELETE https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "Wvqz2qD1",
  "type": "action",
  "deleted": true
}

List all actions

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

Parameters

starting_after

string

Display results listed after (older) than the given id.

ending_before

string

Display results listed before (more recent) than the given id.

limit

integer

Limit how many results to show. Default is 25. Maximum is 100.

curl -G https://api.hellotext.com/v1/attribution/actions \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "actions": [
    {
      "id": "Wvqz2qD1",
      "type": "action",
      "created_at": 1665684173,
      "goal": false,
      "name": "signup_form.completed",
      "title": "Signup-form completed"
    },
    {...},
    {...}
  ]
}

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.

  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

string

Unique identifier of the tracking event.

type

string

Type of object. This is always app.

created_at

epoch

Date of creation of the app object.

image_url

url

An URL of the application icon in high resolution. We will download the image and store it on our servers.

metadata

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.

name

string

The name of the application. Duplicate names are not allowed.

{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173
  "image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
  "metadata": {},
  "name": "Beauty & Care",
}

Create an app

Creates a new app.

Parameters

image_url

url

An URL of the application icon in high resolution. We will download the image and store it on our servers.

name

string

Required

The name of the application. Duplicate names are not allowed.

curl https://api.hellotext.com/v1/attribution/apps \
  -d name="Beauty & Care" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173
  "image_url": null,
  "metadata": {},
  "name": "Beauty & Care",
}

Retrieve an app

Retrieves an existing app.

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

image_url

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

name

string

The name of the application. Duplicate names are not allowed.

curl https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
  -d name="Beauty & More" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173
  "image_url": null,
  "metadata": {},
  "name": "Beauty & More",
}

Delete an app

Permanently deletes the specified app.

curl -X DELETE https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xnqJQ47v",
  "type": "app",
  "deleted": true
}

List all apps

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

Parameters

starting_after

string

Display results listed after (older) than the given id.

ending_before

string

Display results listed before (more recent) than the given id.

limit

integer

Limit how many results to show. Default is 25. Maximum is 100.

curl -G https://api.hellotext.com/v1/attribution/apps \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "apps": [
    {
      "id": "xnqJQ47v",
      "type": "app",
      "created_at": 1665684173
      "image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
      "metadata": {},
      "name": "Beauty & Care",
    },
    {...},
    {...}
  ]
}

Carts

Carts objects represent shopping carts objects that can be used to determine what items the profile has in the cart at a moment in time.

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

You can track when items are added to the cart, removed from the cart, or when the cart was abandoned.

Learn how Track cart events.

  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

string

Unique identifier of the cart object.

type

string

Type of object. This is always cart.

created_at

epoch

Date of creation of the cart object.

metadata

hash

Set of key-value pairs that you can attach to the cart. This can be useful for storing additional information about the object in a structured format.

products

array

A collection of products included in the cart at the current moment in time.

profile

string

The identifier of the profile that this cart belongs to.

reference

string

The cart number or original identifier from the external source that created the cart.

session

string

The identifier of the session that this cart belongs to.

source

string

The source or platform where this cart was generated from.

{
  "id": "wx4Vn4no",
  "type": "cart",
  "created_at": 1665684173
  "metadata": {},
  "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"
      ],
    },
    "reference": "1234"
  ],
  "profile": "MzYwlE50",
  "reference": "ABC123",
  "session": "Vdqlg4nL",
  "source": "shopify",
}

Create a cart

Creates a new cart.

Parameters

metadata

hash

Set of key-value pairs that you can attach to the cart. This can be useful for storing additional information about the object in a structured format.

products

array

A collection of products included in the cart at the current moment in time.

profile

string

The unique identifier of the profile that this cart belongs to. Required if no session is provided.

reference

string

The cart number or original identifier from the external source that created the cart.

session

string

The unique identifier of the session that this cart belongs to. Required if no profile is provided. It can be used to associate the cart with an undefined profile. And later attaching the Cart to the profile once the profile is known.

source

string

The source or platform where this cart was generated from.

curl https://api.hellotext.com/v1/attribution/carts \
  -d metadata[attribute1]="value1" \
  -d metadata[attribute2]="value2" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "wx4Vn4no",
  "type": "cart",
  "created_at": 1665684173
  "metadata": {
    "attribute1": "value1",
    "attribute2": "value2",
  },
  "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"
      ],
    },
    "reference": "1234"
  ],
  "reference": "ABC123",
  "source": "shopify",
}

Retrieve a cart

Retrieves an existing cart.

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

metadata

hash

Set of key-value pairs that you can attach to the cart. This can be useful for storing additional information about the object in a structured format.

products

array

A collection of products identifiers that replace the current items in the cart. Passing an empty value of [] will remove all the items from the cart. Ignoring the parameter will not change the current items in the cart.

profile

string

The unique identifier of the profile that this cart belongs to. Required if no session is provided.

session

string

curl https://api.hellotext.com/v1/attribution/carts/wx4Vn4no \
  -d name="Beauty & More" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "wx4Vn4no",
  "type": "cart",
  "created_at": 1665684173
  "metadata": {
    "attribute1": "value1",
    "attribute2": "value2",
  },
  "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"
      ],
    },
    "reference": "1234"
  ],
  "reference": "ABC123",
  "source": "shopify",
}

Delete a cart

Permanently deletes the specified cart.

curl -X DELETE https://api.hellotext.com/v1/attribution/carts/wx4Vn4no \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "wx4Vn4no",
  "type": "cart",
  "deleted": true
}

List all carts

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

Parameters

starting_after

string

Display results listed after (older) than the given id.

ending_before

string

Display results listed before (more recent) than the given id.

limit

integer

Limit how many results to show. Default is 25. Maximum is 100.

curl -G https://api.hellotext.com/v1/attribution/carts \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "carts": [
     {
      "id": "wx4Vn4no",
      "type": "cart",
      "created_at": 1665684173
      "metadata": {
        "attribute1": "value1",
        "attribute2": "value2",
      },
      "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"
          ],
        },
        "reference": "1234"
      ],
      "reference": "ABC123",
      "source": "shopify",
    },
    {...},
    {...}
  ]
}

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

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.

  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