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
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..."
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.
{
"errors": [
{
"type": "parameter_missing",
"message": "This parameter is required.",
"parameter": "name"
}
]
}
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.
curl -G https://api.hellotext.com/v1/profiles \
-d starting_after="BvYeyVYz" \
-d limit=10 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
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
POST
v1/profiles/:id/subscribe
POST
v1/profiles/:id/unsubscribe
phone, listed in e164 format.
{
"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",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"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"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com"
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001"
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed"
}Creates a new profile.
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.
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.
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.
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.
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[gVlpOkwJ]=MyValue.
curl -X POST 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"
}Retrieves an existing profile.
curl -G https://api.hellotext.com/v1/profiles/MzYwlE50
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Updates the specified profile with the provided information.
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={}.
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[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 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.
[] will remove the profile from every list.
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[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 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[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.
curl -X PATCH 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
}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
}Lists existing profiles sorting by most recent ones. Pagination parameters are available in lists.
curl -G https://api.hellotext.com/v1/profiles
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"profiles": [
{
"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",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"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"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com"
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001"
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed"
},
"{...}",
"{...}"
]
}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",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"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"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com"
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001"
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed"
}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",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"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"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com"
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001"
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "unsubscribed"
}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 and an optional name. 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
{
"id": "OBYBnY69",
"type": "property",
"created_at": 1665684173,
"kind": "text",
"name": "My Property",
"position": 8,
"profile": null
}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.
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.
{
"id": "MQNKalb7",
"kind": "address",
"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 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.
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
}{
"id": "MQNKalb7",
"kind": "checkbox",
"name": null,
"value": false
}{
"id": "MQNKalb7",
"kind": "company",
"name": null,
"value": "ACME Corporation"
}{
"id": "MQNKalb7",
"kind": "date",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
}{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com"
}{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}{
"id": "MQNKalb7",
"kind": "mercadolibre",
"name": null,
"value": "WILLE900001"
}{
"id": "MQNKalb7",
"kind": "number",
"name": null,
"value": 29.99
}{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001"
}{
"id": "MQNKalb7",
"kind": "tags",
"name": null,
"value": [
"tag1",
"tag2"
]
}{
"id": "MQNKalb7",
"kind": "text",
"name": null,
"value": "Long lasting customer"
}{
"id": "MQNKalb7",
"kind": "url",
"name": null,
"value": "https://www.hellotext.com"
}Creates a new property.
phone
email
url
date
tags
text
number
checkbox
curl -X POST 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": "OBYBnY69"
}Retrieves an existing property.
curl -G https://api.hellotext.com/v1/properties/OBYBnY69
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Updates the specified property with the provided information.
position='' moves the property to the bottom of the properties list.
curl -X PATCH https://api.hellotext.com/v1/properties/:id
-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
}Permanently deletes the specified property.
curl -X DELETE https://api.hellotext.com/v1/properties/OBYBnY69
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "OBYBnY69",
"type": "property",
"deleted": true
}Lists existing properties sorting by most recent ones. Pagination parameters are available in lists.
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 act as logical grouping of profiles.
POST
v1/lists
GET
v1/lists/:id
PATCH
v1/lists/:id
DELETE
v1/lists/:id
GET
v1/lists
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}Creates a new list.
curl -X POST https://api.hellotext.com/v1/lists
-d name="Beauty & Care"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "zN4Xx4Km",
"type": "list",
"name": "Beauty & Care",
"created_at": 1665684173
}Retrieves an existing list
curl -G https://api.hellotext.com/v1/lists/zN4Xx4Km
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Updates a list
curl -X PATCH https://api.hellotext.com/v1/lists/zN4Xx4Km
-d name="Loyal customers"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "zN4Xx4Km",
"type": "list",
"name": "Loyal customers",
"created_at": 1665684173
}Deletes a list. Profiles in the list will not be deleted.
curl -X DELETE https://api.hellotext.com/v1/lists/zN4Xx4Km
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "zN4Xx4Km",
"type": "list",
"deleted": true
}Lists existing lists sorting by most recent ones. Pagination parameters are available in lists.
curl -G https://api.hellotext.com/v1/lists
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
},
"{...}",
"{...}"
]
}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",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"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"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com"
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001"
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed"
}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",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"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"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com"
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001"
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed"
}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
{
"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
}Creates a new coupon.
SALE. Case-sensitive. Duplicate names are not allowed.
curl -X POST 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
}Retrieves an existing coupon.
curl -G https://api.hellotext.com/v1/coupons/xJEOaPdk
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Updates the specified coupon with the provided information.
SALE. Case-sensitive. Duplicate names are not allowed.
curl -X PATCH 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
}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
}Lists existing coupons sorting by most recent ones. Pagination parameters are available in lists.
curl -G https://api.hellotext.com/v1/coupons
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"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",
"reference": null
},
"{...}",
"{...}"
]
}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 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.
app.installed
app.removed
app.spent
null. Required if action=app.spent.
app parameter. The app will be created and have the event tracked for
amount given in ISO 4217 format. Default value is always USD. Required if action=app.spent.
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.
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.
created_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 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.
cart.abandoned
cart.added
cart.removed
null.
id, reference or sku) and product_parameters and product_variant_parameters. Required when action is cart.added or cart.removed. 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. reference or sku for the product or product variant to avoid creating duplicate products.
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.
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.
created_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 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.
null.
coupon parameter. The coupon will be created and have the event tracked for.
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.
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.
created_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 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.
null.
form parameter. The form will be created and have the event tracked for.
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.
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.
created_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 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.
order.cancelled
order.confirmed
order.delivered
order.placed
order.printed_label
order.shipped
null.
order parameter. The order will be created and have the event tracked for.
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.
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.
created_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 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.
This endpoint can be used with Products and Product variants. If you want to track an existing Product or Product Variant, make sure to either pass an existing record's id, reference or sku. If you want to create a new Product, you should pass the product_parameters parameter. Similarly, if you want to create a new Product Variant, make sure to pass the product_variant_parameters instead.
product.purchased
product.viewed
null.
id, reference or sku of an existing product object. Optional when you pass product_parameters or product_variant. Required when passing product_variant_parameters.
product parameter. The product will be created and have the event tracked for.
id, reference or sku of an existing product variant object. Optional when you specify product_variant_parameters.
product_variant parameter. The product variant will be created and have the event tracked for. When passing this parameter, make sure to also specify the product via the product parameter.
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.
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.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="product.purchased" \
-d product=vxqQJ3Yg \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
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.
refund.received
refund.requested
null.
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.
refund parameter. The refund will be created and have the event tracked for.
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.
created_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"
}
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.
null.
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.
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.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="signup_form.completed" \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
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 for more information.
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
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.
action parameter when tracking an event. Duplicate names are not allowed.
true. false. However, if the action is not important, you can mark it as passive.
{
"id": "Wvqz2qD1",
"type": "action",
"created_at": 1665684173,
"goal": false,
"name": "signup_form.completed",
"passive": true,
"title": "Signup-form completed"
}Creates a new action.
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.
action parameter when tracking an event. Duplicate names are not allowed.
curl -X POST 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"
}Retrieves an existing action.
curl -G https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Updates the specified action with the provided information.
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.
action parameter when tracking an event. Duplicate names are not allowed.
curl -X PATCH https://api.hellotext.com/v1/attribution/actions/:id
-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"
}Permanently deletes the specified action.
This action is irreversible. Deleting an action will also delete all of the tracked events associated with it. Be careful when using this endpoint.
curl -X DELETE https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "Wvqz2qD1",
"type": "action",
"deleted": true
}Lists existing actions sorting by most recent ones. Pagination parameters are available in lists.
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",
"passive": true,
"title": "Signup-form completed"
},
"{...}",
"{...}"
]
}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
{
"id": "xnqJQ47v",
"type": "app",
"created_at": 1665684173
"image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
"metadata": {},
"name": "Beauty & Care",
}
Creates a new app.
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",
}
Retrieves an existing app.
curl -G https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Updates the specified app with the provided information.
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",
}
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
}
Lists existing apps sorting by most recent ones. Pagination parameters are available in lists.
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 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
{
"id": "wx4Vn4no",
"type": "cart",
"created_at": 1665684173,
"items": [
{
"id": "wx4Vn4no",
"type": "cart_item",
"created_at": 1665684173,
"price": {
"amount": "100.00",
"converted_amount": "100.00",
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3Yg",
"quantity": 1
},
"{...}",
"{...}"
],
"metadata": {
},
"profile": "MzYwlE50",
"reference": "ABC123",
"session": "Vdqlg4nL",
"source": null
}Creates a new cart.
session is provided.
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
curl -X POST 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,
"items": [
{
"id": "wx4Vn4no",
"type": "cart_item",
"created_at": 1665684173,
"price": {
"amount": "100.00",
"converted_amount": "100.00",
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3Yg",
"quantity": 1
},
"{...}",
"{...}"
],
"metadata": {
"attribute1": "value1",
"attribute2": "value2"
},
"profile": "MzYwlE50",
"reference": "ABC123",
"session": "Vdqlg4nL",
"source": null
}Retrieves an existing cart.
curl -G https://api.hellotext.com/v1/attribution/carts/wx4Vn4no
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Updates the specified cart with the provided information.
[] will remove all the items from the cart. Ignoring the parameter will not change the current items in the cart.
session is provided.
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
curl -X PATCH https://api.hellotext.com/v1/attribution/carts/wx4Vn4no
-d metadata[attribute1]=value1
-d metadata[attribute2]=value2
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "wx4Vn4no",
"type": "cart",
"created_at": 1665684173,
"items": [
{
"id": "wx4Vn4no",
"type": "cart_item",
"created_at": 1665684173,
"price": {
"amount": "100.00",
"converted_amount": "100.00",
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3Yg",
"quantity": 1
},
"{...}",
"{...}"
],
"metadata": {
"attribute1": "value1",
"attribute2": "value2"
},
"profile": "MzYwlE50",
"reference": "ABC123",
"session": "Vdqlg4nL",
"source": null
}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
}Lists existing carts sorting by most recent ones. Pagination parameters are available in lists.
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,
"items": [
{
"id": "wx4Vn4no",
"type": "cart_item",
"created_at": 1665684173,
"price": {
"amount": "100.00",
"converted_amount": "100.00",
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3Yg",
"quantity": 1
},
"{...}",
"{...}"
],
"metadata": {
},
"profile": "MzYwlE50",
"reference": "ABC123",
"session": "Vdqlg4nL",
"source": null
},
"{...}",
"{...}"
]
}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
null.
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.
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.
created_at.
{
"id": "xnqJQ47v",
"type": "event",
"action": {
"id": "Wvqz2qD1",
"name": "order.confirmed",
"title": "Product purchased"
},
"amount": 199.95,
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"created_at": 1665684173,
"currency": "USD",
"metadata": {},
"profile": "MzYwlE50",
"session": "Vdqlg4nL",
"trackable": {
"id": "ro4a731w",
"type": "order",
"amount": 199.95,
"currency": "USD",
"product_ids": ["xnqJQ47v"]
},
"tracked_at": "1665684173",
}
Retrieves an existing event.
curl -G https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Updates the specified event with the provided information.
null.
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.
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.
created_at.
curl https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
-d amount=295.00 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "xnqJQ47v",
"type": "event",
"action": {
"id": "Wvqz2qD1",
"name": "order.confirmed",
"title": "Product purchased"
},
"amount": 295.00,
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"created_at": 1665684173,
"currency": "USD",
"metadata": {},
"profile_id": "MzYwlE50",
"session_id": "Vdqlg4nL",
"trackable": {
"id": "ro4a731w",
"type": "order",
"amount": 199.95,
"currency": "USD",
"product_ids": ["xnqJQ47v"]
},
"tracked_at": "1665684173",
}
Permanently deletes the specified event.
curl -X DELETE https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "xnqJQ47v",
"type": "event",
"deleted": true
}
Lists existing events sorting by most recent ones. Pagination parameters are available in lists.
curl -G https://api.hellotext.com/v1/attribution/events \
-d limit=5 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"events": [
{
"id": "xnqJQ47v",
"type": "event",
"action": {
"id": "Wvqz2qD1",
"name": "order.confirmed",
"title": "Product purchased"
},
"amount": 199.95,
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"created_at": 1665684173
"currency": "USD",
"metadata": {},
"profile": "MzYwlE50",
"session": "Vdqlg4nL",
"trackable": {
"id": "ro4a731w",
"type": "order",
"amount": 199.95,
"currency": "USD",
"product_ids": ["xnqJQ47v"]
},
"tracked_at": "1665684173"
},
{...},
{...}
]
}
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.
POST /v1/attribution/forms
GET /v1/attribution/forms/:id
PATCH /v1/attribution/forms/:id
DELETE /v1/attribution/forms/:id
GET /v1/attribution/forms
{
"id": "O8lOzkwa",
"type": "form",
"created_at": 1665684173
"metadata": {},
"name": "Sign-Up Form",
}
Creates a new form.
curl https://api.hellotext.com/v1/attribution/forms \
-d name="Sign-Up Form" \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "O8lOzkwa",
"type": "form",
"created_at": 1665684173
"metadata": {}
"name": "Sign-Up Form",
}
Retrieves an existing form.
curl -G https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Updates the specified form with the provided information.
curl https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
-d name="Completion Form" \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "O8lOzkwa",
"type": "form",
"created_at": 1665684173
"metadata": {},
"name": "Completion Form",
}
Permanently deletes the specified form.
curl -X DELETE https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "O8lOzkwa",
"type": "form",
"deleted": true
}
Lists existing forms sorting by most recent ones. Pagination parameters are available in lists.
curl -G https://api.hellotext.com/v1/attribution/forms \
-d limit=5 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"forms": [
{
"id": "O8lOzkwa",
"type": "form",
"created_at": 1665684173
"metadata": {},
"name": "Sign-Up Form",
},
{...},
{...}
]
}
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.
POST /v1/attribution/orders
GET /v1/attribution/orders/:id
PATCH /v1/attribution/orders/:id
DELETE /v1/attribution/orders/:id
GET /v1/attribution/orders
collect when customers buys directly on store or pickup from store and deliver when shipping the package to the customer address. This attribute is not set by default.
collect
deliver
{
"id": "ro4a731w",
"type": "order",
"created_at": 1665684173
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"quantity": 1,
"price": {
"amount": "395.00",
"currency": "USD"
}
}
],
"metadata": {},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD",
}
}
Creates a new order.
collect when customers buys directly on store or pickup from store and deliver when shipping the package to the customer address. This attribute is not set by default.
collect
deliver
id, reference or sku) and product_parameters and product_variant_parameters. product_parameters or product_variant_parameters, the product or product variant will be created automatically if it does not exist already. reference or sku for the product or product variant to avoid creating duplicate products. You can also specify the quantity of the product with the quantity attribute.
curl https://api.hellotext.com/v1/attribution/orders \
-d amount=395.00 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "ro4a731w",
"type": "order",
"created_at": 1665684173
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"quantity": 1,
"price": {
"amount": "395.00",
"currency": "USD"
}
}
],
"metadata": {},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD",
}
}
Retrieves an existing order.
curl -G https://api.hellotext.com/v1/attribution/orders/ro4a731w \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Updates the specified order with the provided information.
collect when customers buys directly on store or pickup from store and deliver when shipping the package to the customer address. This attribute is not set by default.
collect
deliver
curl https://api.hellotext.com/v1/attribution/orders/ro4a731w \
-d metadata[state]="paid" \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "ro4a731w",
"type": "order",
"created_at": 1665684173
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"quantity": 1,
"price": {
"amount": "395.00",
"currency": "USD"
}
}
],
"metadata": {},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD",
}
}
Permanently deletes the specified order.
curl -X DELETE https://api.hellotext.com/v1/attribution/orders/ro4a731w \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "ro4a731w",
"type": "order",
"deleted": true
}
Lists existing orders sorting by most recent ones. Pagination parameters are available in lists.
curl -G https://api.hellotext.com/v1/attribution/orders \
-d limit=5 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"orders": [
{
"id": "ro4a731w",
"type": "order",
"created_at": 1665684173
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"quantity": 1,
"price": {
"amount": "395.00",
"currency": "USD"
}
}
],
"metadata": {},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD",
}
},
{...},
{...}
]
}
Product objects represent products that you can use to track actions through its lifecycle such as product.purchased and product.viewed or cart.added and cart.removed.
Product objects act as logical groups where you can group multiple actions to the same object for better reporting.
POST
v1/attribution/products
GET
v1/attribution/products/:id
PATCH
v1/attribution/products/:id
DELETE
v1/attribution/products/:id
GET
v1/attribution/products
{
"id": "vxqQJ3Yg",
"type": "product",
"brand": "Adidas",
"categories": [
"shoes"
],
"collection": [
"350 v2"
],
"created_at": 1665684173,
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"reference": null,
"sku": "1234567890",
"source": null,
"tags": [
"Sneakers"
],
"variants": [
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
},
"{...}",
"{...}"
]
}Creates a new product.
curl -X POST https://api.hellotext.com/v1/attribution/products
-d name="Sign-Up Form"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product",
"brand": "Adidas",
"categories": [
"shoes"
],
"collection": [
"350 v2"
],
"created_at": 1665684173,
"metadata": {
},
"name": "Sign-Up Form",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"reference": null,
"sku": "1234567890",
"source": null,
"tags": [
"Sneakers"
],
"variants": [
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
},
"{...}",
"{...}"
]
}Retrieves an existing product. You can find a product by it's id, reference or sku.
curl -G https://api.hellotext.com/v1/attribution/products/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Updates the specified product with the provided information. You can update a product by it's id, reference or sku.
curl -X PATCH https://api.hellotext.com/v1/attribution/products/:id
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product",
"brand": "Adidas",
"categories": [
"shoes"
],
"collection": [
"350 v2"
],
"created_at": 1665684173,
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"reference": null,
"sku": "1234567890",
"source": null,
"tags": [
"Sneakers"
],
"variants": [
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
},
"{...}",
"{...}"
]
}Permanently deletes the specified product. You can delete a product by it's id, reference or sku.
curl -X DELETE https://api.hellotext.com/v1/attribution/products/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product",
"deleted": true
}Lists existing products sorting by most recent ones. Pagination parameters are available in lists.
curl -G https://api.hellotext.com/v1/attribution/products
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"products": [
{
"id": "vxqQJ3Yg",
"type": "product",
"brand": "Adidas",
"categories": [
"shoes"
],
"collection": [
"350 v2"
],
"created_at": 1665684173,
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"reference": null,
"sku": "1234567890",
"source": null,
"tags": [
"Sneakers"
],
"variants": [
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
},
"{...}",
"{...}"
]
},
"{...}",
"{...}"
]
}The Product Variant object represents a specific variation of a product. For example, a product with a size and color can have multiple variants. Each variant can have a different price, SKU or reference.
Variants can be created directly when creating a Product through the variants parameter. Or when updating a product by passing the new_variants parameter.
GET
v1/attribution/variants/:id
PATCH
v1/attribution/variants/:id
DELETE
v1/attribution/variants/:id
POST
v1/attribution/products/:product/variants
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
}Retrieves the details of an existing Product Variant. You can fetch a Product Variant by its id, reference or sku.
curl -G https://api.hellotext.com/v1/attribution/variants/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Updates the specified Product Variant. You can update a Product Variant by its id, reference or sku.
curl -X PATCH https://api.hellotext.com/v1/attribution/variants/vxqQJ3Yg
-d name="Yeezy boost 350 v2"
-d sku="5678"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3YQ",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "5678",
"source": null
}Destroys the specified Product Variant. You can destroy a Product Variant by its id, reference or sku.
curl -X DELETE https://api.hellotext.com/v1/attribution/variants/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product_variant",
"deleted": true
}Creates a new Product Variant.
Make sure to replace the :product with the id, reference or sku of the parent Product. We try to find the parent product firstly by the id, then by the reference and finally by the sku. When no parent product was found, a 404 error will be returned.
curl -X POST https://api.hellotext.com/v1/attribution/products/vxqQJ3YQ/variants
-d name="Yeezy boost 350 v2"
-d sku="1234567890"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
}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.
POST /v1/attribution/refunds
GET /v1/attribution/refunds/:id
PATCH /v1/attribution/refunds/:id
DELETE /v1/attribution/refunds/:id
GET /v1/attribution/refunds
order or product refunded. This attribute is optional and by default its value is set to null.
{
"id": "w83Pj4PY",
"type": "refund",
"created_at": 1665684173
"metadata": {},
"profile": null,
"reference": null,
"refundable": {
"id": "ro4a731w",
"type": "order",
"amount": "199.95",
"created_at": 1665684173,
"currency": "USD",
"metadata": {}
},
"source": null,
"total": {
"amount": "199.95",
"converted_amount": "199.95",
"converted_currency": "EUR",
"currency": "USD",
}
}
Creates a new refund.
refundable object.
refundable object.
curl https://api.hellotext.com/v1/attribution/refunds \
-d amount=19.90 \
-d order=ro4a731w \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "w83Pj4PY",
"type": "refund",
"created_at": 1665684173
"metadata": {},
"profile": null,
"reference": null,
"refundable": {
"id": "ro4a731w",
"type": "order",
"amount": "199.95",
"created_at": 1665684173,
"currency": "USD",
"metadata": {}
},
"source": null,
"total": {
"amount": "199.95",
"converted_amount": "199.95",
"converted_currency": "EUR",
"currency": "USD",
}
}
Retrieves an existing refund.
curl -G https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Updates the specified refund with the provided information.
refundable object.
refundable object.
curl https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
-d amount=24.90 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "w83Pj4PY",
"type": "refund",
"created_at": 1665684173
"metadata": {},
"profile": null,
"reference": null,
"refundable": {
"id": "ro4a731w",
"type": "order",
"amount": "199.95",
"created_at": 1665684173,
"currency": "USD",
"metadata": {}
},
"source": null,
"total": {
"amount": "199.95",
"converted_amount": "199.95",
"converted_currency": "EUR",
"currency": "USD",
}
}
Permanently deletes the specified refund.
curl -X DELETE https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "w83Pj4PY",
"type": "refund",
"deleted": true
}
Lists existing refunds sorting by most recent ones. Pagination parameters are available in lists.
curl -G https://api.hellotext.com/v1/attribution/refunds \
-d limit=5 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"refunds": [
{
"id": "w83Pj4PY",
"type": "refund",
"created_at": 1665684173
"metadata": {},
"profile": null,
"reference": null,
"refundable": {
"id": "ro4a731w",
"type": "order",
"amount": "199.95",
"created_at": 1665684173,
"currency": "USD",
"metadata": {}
},
"source": null,
"total": {
"amount": "199.95",
"converted_amount": "199.95",
"converted_currency": "EUR",
"currency": "USD",
}
},
{...},
{...}
]
}
Sessions are unique identifiers generated when visitors click on short links and attached to the destination URL as a GET parameter called hello_session. You can think of a session as sharing the same known meaning from web browsers: it represents an active visitor browser and is device specific.
Tracking events specifying the session identifier will also keep an automatic association to the customer profile who clicked on the short link, aggregating the events to his history of activities and to the reporting of the campaign or journey where the message with the short link was present.
When tracking client-side events with the Hellotext.js library, there is no need to explicitly specify the session identifier as the library will take care of it behind the scenes.
To improve security and privacy we discourage disclosing the identifier of the profile directly on the browser. Because of this, the client-side Hellotext.js library only accepts to track events specifying a session and not to a profile directly.
It is possible to track events for non-identified visitors too. The Hellotext.js library creates a new session identifier for every new visitor when it does not find it defined as a parameter. You can store this session identifier, and later attach the profile when it becomes known, for example when the visitor logins into the store, places an order, or subscribes entering his phone number.
PATCH /v1/sessions/:id
Once the profile is known, attach it to the session so all its events tracked become part of his history of activities.
If you also want to change the session to a different profile, set the new profile identifier in the profile parameter and the session will be assigned to the new profile.
All carts associated with a session will be assigned to the profile you attach the session to.