#Integration API

The Integration API is how you push data into the Talon.One environment. You can create profiles for your customers, sessions to group their activity, and custom events to track specific actions that do not fit into the session data model. You will need Authentication to make requests to the API.

#Update a Customer Profile

PUT /v1/customer_profiles/{integrationId}

Update (or create) a Customer Profile. This profile information can then be matched and/or updated by campaign Rules.

The integrationId may be any identifier that will remain stable for the customer. For example, you might use a database ID, an email, or a phone number as the integrationId. It is vital that this ID not change over time, so don't use any identifier that the customer can update themselves. E.g. if your application allows a customer to update their e-mail address, you should instead use a database ID.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

Parameters

integrationId string - The custom identifier for this profile, must be unique within the account.

Request

curl https://example.talon.one/v1/customer_profiles/42 \
 -X PUT \
 -d '{
  "attributes": {
    "AdditionalEmails": "Additional Emails",
    "Billing": "Default billing country",
    "VenueBudgetCategory": "Venue budget category"
  }
}'

Response (200)

{
  "event": {
    "applicationId": 99,
    "attributes": {
      "OperatingSystem": "Operating System",
      "OrderCount": 38,
      "ShippingName": "Session shipping Name"
    },
    "created": "2016-11-20T20:20:19Z",
    "effects": [
      "createApplication",
      "put",
      "setDiscount"
    ],
    "id": 60,
    "ledgerEntries": [
      {
        "accountId": 46,
        "amount": 49,
        "created": "2016-07-08T06:13:09Z",
        "eventId": 73,
        "expiryDate": "2018-11-20T15:39:19.949628807Z",
        "id": 52,
        "loyaltyProgramId": 70,
        "profileId": "73",
        "reason": "IntegrationState.event...Event.ledgerEntries...LedgerEntry.reason",
        "referenceId": 75
      },
      {
        "accountId": 29,
        "amount": 38,
        "created": "2016-01-31T03:56:28Z",
        "eventId": 71,
        "expiryDate": "2019-03-19T15:39:19.949628807Z",
        "id": 31,
        "loyaltyProgramId": 16,
        "profileId": "7",
        "reason": "IntegrationState.event...Event.ledgerEntries...LedgerEntry.reason",
        "referenceId": 43
      }
    ],
    "meta": {},
    "profileId": "45",
    "sessionId": "45",
    "type": "type"
  },
  "profile": {
    "accountId": 26,
    "attributes": {
      "BillingCity": "Session billing city",
      "BillingPostalCode": "Default billing postal code",
      "SessionDuration": "2016-08-21T21:30:47Z",
      "ShippingAddress2": "Default shipping address field 2"
    },
    "closedSessions": 65,
    "created": "2016-10-13T00:33:44Z",
    "integrationId": "NewCustomerProfile69",
    "lastActivity": "2016-01-15T18:18:54Z",
    "loyaltyMemberships": [
      {
        "joined": "2016-06-07T03:01:55Z",
        "loyaltyProgramId": 6
      },
      {
        "joined": "2016-01-21T15:47:00Z",
        "loyaltyProgramId": 6
      },
      {
        "joined": "2016-01-10T22:23:57Z",
        "loyaltyProgramId": 54
      },
      {
        "joined": "2016-10-08T04:16:56Z",
        "loyaltyProgramId": 5
      }
    ],
    "totalSales": 64.11
  },
  "session": {
    "applicationId": 14,
    "attributes": {
      "ShippingAddress3": "Default shipping address field 3"
    },
    "cartItems": [
      {
        "adjustment": {
          "payFromLoyaltyProgram": 46,
          "pointPayment": 2,
          "remainingPrice": 80.59
        },
        "attributes": {
          "FlightNumberReturn": "Flight number return",
          "OperatingSystem": "Operating System"
        },
        "category": "home goods",
        "height": 6.33,
        "length": 4.92,
        "name": "flight to Berlin",
        "position": 16.57,
        "price": 29.07,
        "quantity": 24,
        "sku": "wojk773jsy",
        "weight": 6.39,
        "width": 4.34
      }
    ],
    "coupon": "qwosztcem4",
    "created": "2016-11-25T02:43:32Z",
    "discounts": {
      "free item": 2,
      "free shipping": 5,
      "referred coupon": 2
    },
    "firstSession": true,
    "integrationId": "NewCustomerProfile69",
    "profileId": "5",
    "referral": "vwu22i7o5u",
    "state": "open",
    "total": 86.27
  }
}

#Update a Customer Session

PUT /v1/customer_sessions/{customerSessionId}

Update (or create) a Customer Session. For example, the items in a customers cart are part of a session.

The Talon.One platform supports multiple simultaneous sessions for the same profile, so if you have multiple ways of accessing the same application you have the option of either tracking multiple independent sessions or using the same session across all of them. You should share sessions when application access points share other state, such as the users cart. If two points of access to the application have independent state (e.g. a user can have different items in their cart across the two) they should use independent customer session ID's.

The profileId parameter in the request body should correspond to an integrationId for a customer profile, to track an anonymous session use the empty string ("") as the profileId. Note that you do not need to create a customer profile first: if the specified profile does not yet exist, an empty profile will be created automatically.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

The currency for the session and the cart items in the session is the same as that of the application with which the session is associated.

Parameters

customerSessionId string - The custom identifier for this session, must be unique within the account.

Request

curl https://example.talon.one/v1/customer_sessions/C156902 \
 -X PUT \
 -d '{
  "attributes": {
    "BookingClass": "Travel booking class",
    "TimeOnPage": "2016-01-10T21:18:59Z"
  },
  "cartItems": [],
  "coupon": "vmdan1l98k",
  "profileId": "90",
  "referral": "w1uclbva8p",
  "state": "cancelled",
  "total": 22.79
}'

Response (200)

{
  "event": {
    "applicationId": 99,
    "attributes": {
      "OperatingSystem": "Operating System",
      "OrderCount": 38,
      "ShippingName": "Session shipping Name"
    },
    "created": "2016-11-20T20:20:19Z",
    "effects": [
      "createApplication",
      "put",
      "setDiscount"
    ],
    "id": 60,
    "ledgerEntries": [
      {
        "accountId": 46,
        "amount": 49,
        "created": "2016-07-08T06:13:09Z",
        "eventId": 73,
        "expiryDate": "2018-11-20T15:39:19.949628807Z",
        "id": 52,
        "loyaltyProgramId": 70,
        "profileId": "73",
        "reason": "IntegrationState.event...Event.ledgerEntries...LedgerEntry.reason",
        "referenceId": 75
      },
      {
        "accountId": 29,
        "amount": 38,
        "created": "2016-01-31T03:56:28Z",
        "eventId": 71,
        "expiryDate": "2019-03-19T15:39:19.949628807Z",
        "id": 31,
        "loyaltyProgramId": 16,
        "profileId": "7",
        "reason": "IntegrationState.event...Event.ledgerEntries...LedgerEntry.reason",
        "referenceId": 43
      }
    ],
    "meta": {},
    "profileId": "45",
    "sessionId": "45",
    "type": "type"
  },
  "profile": {
    "accountId": 26,
    "attributes": {
      "BillingCity": "Session billing city",
      "BillingPostalCode": "Default billing postal code",
      "SessionDuration": "2016-08-21T21:30:47Z",
      "ShippingAddress2": "Default shipping address field 2"
    },
    "closedSessions": 65,
    "created": "2016-10-13T00:33:44Z",
    "integrationId": "NewCustomerProfile69",
    "lastActivity": "2016-01-15T18:18:54Z",
    "loyaltyMemberships": [
      {
        "joined": "2016-06-07T03:01:55Z",
        "loyaltyProgramId": 6
      },
      {
        "joined": "2016-01-21T15:47:00Z",
        "loyaltyProgramId": 6
      },
      {
        "joined": "2016-01-10T22:23:57Z",
        "loyaltyProgramId": 54
      },
      {
        "joined": "2016-10-08T04:16:56Z",
        "loyaltyProgramId": 5
      }
    ],
    "totalSales": 64.11
  },
  "session": {
    "applicationId": 14,
    "attributes": {
      "ShippingAddress3": "Default shipping address field 3"
    },
    "cartItems": [
      {
        "adjustment": {
          "payFromLoyaltyProgram": 46,
          "pointPayment": 2,
          "remainingPrice": 80.59
        },
        "attributes": {
          "FlightNumberReturn": "Flight number return",
          "OperatingSystem": "Operating System"
        },
        "category": "home goods",
        "height": 6.33,
        "length": 4.92,
        "name": "flight to Berlin",
        "position": 16.57,
        "price": 29.07,
        "quantity": 24,
        "sku": "wojk773jsy",
        "weight": 6.39,
        "width": 4.34
      }
    ],
    "coupon": "qwosztcem4",
    "created": "2016-11-25T02:43:32Z",
    "discounts": {
      "free item": 2,
      "free shipping": 5,
      "referred coupon": 2
    },
    "firstSession": true,
    "integrationId": "NewCustomerProfile69",
    "profileId": "5",
    "referral": "vwu22i7o5u",
    "state": "open",
    "total": 86.27
  }
}

#Track an Event

POST /v1/events

Records an arbitrary event in a customer session. For example, an integration might record an event when a user updates their payment information.

The sessionId body parameter is required, an event is always part of a session. Much like updating a customer session, if either the profile or the session do not exist, a new empty one will be created. Note that if the specified session already exists, it must belong to the same profileId or an error will be returned.

As with customer sessions, you can use an empty string for profileId to indicate that this is an anonymous session.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

Request

curl https://example.talon.one/v1/events \
 -X POST \
 -d '{
  "attributes": {
    "BillingName": "Default billing name"
  },
  "profileId": "42",
  "sessionId": "56",
  "type": "type"
}'

Response (201)

{
  "event": {
    "applicationId": 99,
    "attributes": {
      "OperatingSystem": "Operating System",
      "OrderCount": 38,
      "ShippingName": "Session shipping Name"
    },
    "created": "2016-11-20T20:20:19Z",
    "effects": [
      "createApplication",
      "put",
      "setDiscount"
    ],
    "id": 60,
    "ledgerEntries": [
      {
        "accountId": 46,
        "amount": 49,
        "created": "2016-07-08T06:13:09Z",
        "eventId": 73,
        "expiryDate": "2018-11-20T15:39:19.949628807Z",
        "id": 52,
        "loyaltyProgramId": 70,
        "profileId": "73",
        "reason": "IntegrationState.event...Event.ledgerEntries...LedgerEntry.reason",
        "referenceId": 75
      },
      {
        "accountId": 29,
        "amount": 38,
        "created": "2016-01-31T03:56:28Z",
        "eventId": 71,
        "expiryDate": "2019-03-19T15:39:19.949628807Z",
        "id": 31,
        "loyaltyProgramId": 16,
        "profileId": "7",
        "reason": "IntegrationState.event...Event.ledgerEntries...LedgerEntry.reason",
        "referenceId": 43
      }
    ],
    "meta": {},
    "profileId": "45",
    "sessionId": "45",
    "type": "type"
  },
  "profile": {
    "accountId": 26,
    "attributes": {
      "BillingCity": "Session billing city",
      "BillingPostalCode": "Default billing postal code",
      "SessionDuration": "2016-08-21T21:30:47Z",
      "ShippingAddress2": "Default shipping address field 2"
    },
    "closedSessions": 65,
    "created": "2016-10-13T00:33:44Z",
    "integrationId": "NewCustomerProfile69",
    "lastActivity": "2016-01-15T18:18:54Z",
    "loyaltyMemberships": [
      {
        "joined": "2016-06-07T03:01:55Z",
        "loyaltyProgramId": 6
      },
      {
        "joined": "2016-01-21T15:47:00Z",
        "loyaltyProgramId": 6
      },
      {
        "joined": "2016-01-10T22:23:57Z",
        "loyaltyProgramId": 54
      },
      {
        "joined": "2016-10-08T04:16:56Z",
        "loyaltyProgramId": 5
      }
    ],
    "totalSales": 64.11
  },
  "session": {
    "applicationId": 14,
    "attributes": {
      "ShippingAddress3": "Default shipping address field 3"
    },
    "cartItems": [
      {
        "adjustment": {
          "payFromLoyaltyProgram": 46,
          "pointPayment": 2,
          "remainingPrice": 80.59
        },
        "attributes": {
          "FlightNumberReturn": "Flight number return",
          "OperatingSystem": "Operating System"
        },
        "category": "home goods",
        "height": 6.33,
        "length": 4.92,
        "name": "flight to Berlin",
        "position": 16.57,
        "price": 29.07,
        "quantity": 24,
        "sku": "wojk773jsy",
        "weight": 6.39,
        "width": 4.34
      }
    ],
    "coupon": "qwosztcem4",
    "created": "2016-11-25T02:43:32Z",
    "discounts": {
      "free item": 2,
      "free shipping": 5,
      "referred coupon": 2
    },
    "firstSession": true,
    "integrationId": "NewCustomerProfile69",
    "profileId": "5",
    "referral": "vwu22i7o5u",
    "state": "open",
    "total": 86.27
  }
}

#Create a referral code for an advocate

POST /v1/referrals

Creates a referral code for an advocate. The code will be valid for the referral campaign for which is created, indicated in the campaignId parameter, and will be associated with the profile specified in the advocateProfileIntegrationId parameter as the advocate's profile.

Request

curl https://example.talon.one/v1/referrals \
 -X POST \
 -d '{
  "advocateProfileIntegrationId": "87",
  "campaignId": 3,
  "expiryDate": "2019-01-25T15:39:19.949628807Z",
  "friendProfileIntegrationId": "74",
  "startDate": "2018-10-15T15:39:19.949628807Z"
}'

Response (201)

{
  "advocateProfileIntegrationId": "5",
  "campaignId": 46,
  "code": "4zan11yja9",
  "created": "2016-11-26T12:27:42Z",
  "expiryDate": "2018-11-14T15:39:19.949628807Z",
  "friendProfileIntegrationId": "2",
  "id": 53,
  "startDate": "2018-10-15T15:39:19.949628807Z",
  "usageCounter": 84,
  "usageLimit": 44
}