Quick startIn a NutshellEntitiesAttributesAttribute LibraryFAQ
Management API
OverviewAuthentication

API Reference

API Errors

#Management API

The Management API includes all information about your applications, campaigns, rulesets, attributes, and webhooks.

#Authentication

Management API operations use a simple bearer token to authenticate requests. You can obtain a bearer token from your credentials using the createSession operation. The token property of the response is used to authenticate further requests with an HTTP header like Authorization: Bearer $TOKEN.

#Sessions

Operations for logging in/out of the Campaign Manager.

#Create a Session

POST /v1/sessions

Request

curl https://example.talon.one/v1/sessions \
 -X POST \
 -d '{
  "email": "zakary@heidenreich.org",
  "password": "918fz1xi5u"
}'

Response (201)

{
  "created": "2016-01-18T22:00:49Z",
  "token": "zb8buj39cd",
  "userId": 81
}

#Destroy a Session

DELETE /v1/sessions

Request

curl https://example.talon.one/v1/sessions \
 -X DELETE

Response (204)

{}

#Applications

#Create an Application

POST /v1/applications

Create a new application in the current account.

Request

curl https://example.talon.one/v1/applications \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "caseSensitivity": "insensitive-uppercase",
  "currency": "EUR",
  "description": "description",
  "key": "3lacvox9of93w9t3",
  "name": "ACME MyApplication",
  "timezone": "UTC"
}'

Response (201)

{
  "accountId": 55,
  "caseSensitivity": "sensitive",
  "created": "2016-10-11T18:36:45Z",
  "currency": "EUR",
  "description": "description",
  "id": 68,
  "key": "3lacvox9of93w9t3",
  "modified": "2016-11-13T10:31:45Z",
  "name": "ACME MyApplication",
  "timezone": "UTC"
}

#List Applications

GET /v1/applications

List all application in the current account.

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/applications \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "accountId": 55,
      "caseSensitivity": "sensitive",
      "created": "2016-10-11T18:36:45Z",
      "currency": "EUR",
      "description": "description",
      "id": 68,
      "key": "3lacvox9of93w9t3",
      "modified": "2016-11-13T10:31:45Z",
      "name": "ACME MyApplication",
      "timezone": "UTC"
    }
  ]
}

#Get Application

GET /v1/applications/{applicationId}

Get the application specified by the ID.

Parameters

applicationId integer

Request

curl https://example.talon.one/v1/applications/42 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "accountId": 55,
  "caseSensitivity": "sensitive",
  "created": "2016-10-11T18:36:45Z",
  "currency": "EUR",
  "description": "description",
  "id": 68,
  "key": "3lacvox9of93w9t3",
  "modified": "2016-11-13T10:31:45Z",
  "name": "ACME MyApplication",
  "timezone": "UTC"
}

#Update Application data

PUT /v1/applications/{applicationId}

Change the application specified by the ID.

Parameters

applicationId integer

Request

curl https://example.talon.one/v1/applications/42 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "caseSensitivity": "insensitive-uppercase",
  "currency": "EUR",
  "description": "description",
  "key": "3lacvox9of93w9t3",
  "name": "ACME MyApplication",
  "timezone": "UTC"
}'

Response (200)

{
  "accountId": 55,
  "caseSensitivity": "sensitive",
  "created": "2016-10-11T18:36:45Z",
  "currency": "EUR",
  "description": "description",
  "id": 68,
  "key": "3lacvox9of93w9t3",
  "modified": "2016-11-13T10:31:45Z",
  "name": "ACME MyApplication",
  "timezone": "UTC"
}

#Delete an Application

DELETE /v1/applications/{applicationId}

Delete the application specified by the ID. Also deletes associated data.

Parameters

applicationId integer

Request

curl https://example.talon.one/v1/applications/42 \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#Campaigns

Campaigns are the primary resource used to control the behaviour of the Talon.One Rule Engine. They combine rulesets, coupons, and limits into a single unit.

#Create a Campaign

POST /v1/applications/{applicationId}/campaigns

Parameters

applicationId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "activeRulesetId": 11,
  "attributes": {
    "Email": "Email",
    "FirstOrderDate": "2016-04-05T21:17:16Z",
    "ShippingCountry": "Session shipping country"
  },
  "couponSettings": {
    "couponPattern": "0g5y2i62k0",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "description": "description",
  "endTime": "2018-11-24T15:39:19.949628807Z",
  "features": [],
  "limits": [
    {
      "action": "redeemReferral",
      "entities": [
        "Referral"
      ],
      "limit": 85.22
    },
    {
      "action": "setDiscount",
      "entities": [
        "Referral"
      ],
      "limit": 47.66
    }
  ],
  "name": "10% off dinner for 2 at Sadhu",
  "referralSettings": {
    "couponPattern": "oz6jt1ox10",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "startTime": "2018-10-15T15:39:19.949628807Z",
  "state": "disabled",
  "tags": [
    "new customer promo",
    "country"
  ]
}'

Response (201)

{
  "activeRulesetId": 33,
  "applicationId": 56,
  "attributes": {
    "LastOrderDate": "2016-01-16T06:39:06Z",
    "OrderCount": 78,
    "PaymentMethod": "Session payment method"
  },
  "couponRedemptionCount": 6,
  "couponSettings": {
    "couponPattern": "fz17kz3vxt",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "created": "2016-04-08T02:58:12Z",
  "createdBy": "Campaign.createdBy",
  "description": "description",
  "discountCount": 44,
  "endTime": "2019-03-19T15:39:19.949628807Z",
  "features": [
    "loyalty",
    "referrals",
    "referrals"
  ],
  "id": 32,
  "lastActivity": "2016-10-11T23:08:28Z",
  "limits": [
    {
      "action": "setDiscount",
      "entities": [
        "Referral"
      ],
      "limit": 46.65
    },
    {
      "action": "redeemCoupon",
      "entities": [
        "Referral"
      ],
      "limit": 83.66
    }
  ],
  "name": "10% off dinner for 2 at Sadhu",
  "referralRedemptionCount": 34,
  "referralSettings": {
    "couponPattern": "3vu1ofi6b0",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "startTime": "2018-10-15T15:39:19.949628807Z",
  "state": "enabled",
  "tags": [
    "new customer promo",
    "country"
  ],
  "updated": "2016-04-01T08:01:11Z",
  "updatedBy": "Campaign.updatedBy",
  "userId": 98
}

#List your Campaigns

GET /v1/applications/{applicationId}/campaigns

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
campaignState string - Filter results by the state of the campaign.

Request

curl https://example.talon.one/v1/applications/42/campaigns \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "activeRulesetId": 33,
      "applicationId": 56,
      "attributes": {
        "LastOrderDate": "2016-01-16T06:39:06Z",
        "OrderCount": 78,
        "PaymentMethod": "Session payment method"
      },
      "couponRedemptionCount": 6,
      "couponSettings": {
        "couponPattern": "fz17kz3vxt",
        "validCharacters": [
          "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
          "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
        ]
      },
      "created": "2016-04-08T02:58:12Z",
      "createdBy": "Campaign.createdBy",
      "description": "description",
      "discountCount": 44,
      "endTime": "2019-03-19T15:39:19.949628807Z",
      "features": [
        "loyalty",
        "referrals",
        "referrals"
      ],
      "id": 32,
      "lastActivity": "2016-10-11T23:08:28Z",
      "limits": [
        {
          "action": "setDiscount",
          "entities": [
            "Referral"
          ],
          "limit": 46.65
        },
        {
          "action": "redeemCoupon",
          "entities": [
            "Referral"
          ],
          "limit": 83.66
        }
      ],
      "name": "10% off dinner for 2 at Sadhu",
      "referralRedemptionCount": 34,
      "referralSettings": {
        "couponPattern": "3vu1ofi6b0",
        "validCharacters": [
          "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
          "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
        ]
      },
      "startTime": "2018-10-15T15:39:19.949628807Z",
      "state": "enabled",
      "tags": [
        "new customer promo",
        "country"
      ],
      "updated": "2016-04-01T08:01:11Z",
      "updatedBy": "Campaign.updatedBy",
      "userId": 98
    }
  ]
}

#Get a Campaign

GET /v1/applications/{applicationId}/campaigns/{campaignId}

Parameters

applicationId integer
campaignId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "activeRulesetId": 33,
  "applicationId": 56,
  "attributes": {
    "LastOrderDate": "2016-01-16T06:39:06Z",
    "OrderCount": 78,
    "PaymentMethod": "Session payment method"
  },
  "couponRedemptionCount": 6,
  "couponSettings": {
    "couponPattern": "fz17kz3vxt",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "created": "2016-04-08T02:58:12Z",
  "createdBy": "Campaign.createdBy",
  "description": "description",
  "discountCount": 44,
  "endTime": "2019-03-19T15:39:19.949628807Z",
  "features": [
    "loyalty",
    "referrals",
    "referrals"
  ],
  "id": 32,
  "lastActivity": "2016-10-11T23:08:28Z",
  "limits": [
    {
      "action": "setDiscount",
      "entities": [
        "Referral"
      ],
      "limit": 46.65
    },
    {
      "action": "redeemCoupon",
      "entities": [
        "Referral"
      ],
      "limit": 83.66
    }
  ],
  "name": "10% off dinner for 2 at Sadhu",
  "referralRedemptionCount": 34,
  "referralSettings": {
    "couponPattern": "3vu1ofi6b0",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "startTime": "2018-10-15T15:39:19.949628807Z",
  "state": "enabled",
  "tags": [
    "new customer promo",
    "country"
  ],
  "updated": "2016-04-01T08:01:11Z",
  "updatedBy": "Campaign.updatedBy",
  "userId": 98
}

#Update a Campaign

PUT /v1/applications/{applicationId}/campaigns/{campaignId}

Parameters

applicationId integer
campaignId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "activeRulesetId": 11,
  "attributes": {
    "Email": "Email",
    "FirstOrderDate": "2016-04-05T21:17:16Z",
    "ShippingCountry": "Session shipping country"
  },
  "couponSettings": {
    "couponPattern": "0g5y2i62k0",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "description": "description",
  "endTime": "2018-11-24T15:39:19.949628807Z",
  "features": [],
  "limits": [
    {
      "action": "redeemReferral",
      "entities": [
        "Referral"
      ],
      "limit": 85.22
    },
    {
      "action": "setDiscount",
      "entities": [
        "Referral"
      ],
      "limit": 47.66
    }
  ],
  "name": "10% off dinner for 2 at Sadhu",
  "referralSettings": {
    "couponPattern": "oz6jt1ox10",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "startTime": "2018-10-15T15:39:19.949628807Z",
  "state": "disabled",
  "tags": [
    "new customer promo",
    "country"
  ]
}'

Response (200)

{
  "activeRulesetId": 33,
  "applicationId": 56,
  "attributes": {
    "LastOrderDate": "2016-01-16T06:39:06Z",
    "OrderCount": 78,
    "PaymentMethod": "Session payment method"
  },
  "couponRedemptionCount": 6,
  "couponSettings": {
    "couponPattern": "fz17kz3vxt",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "created": "2016-04-08T02:58:12Z",
  "createdBy": "Campaign.createdBy",
  "description": "description",
  "discountCount": 44,
  "endTime": "2019-03-19T15:39:19.949628807Z",
  "features": [
    "loyalty",
    "referrals",
    "referrals"
  ],
  "id": 32,
  "lastActivity": "2016-10-11T23:08:28Z",
  "limits": [
    {
      "action": "setDiscount",
      "entities": [
        "Referral"
      ],
      "limit": 46.65
    },
    {
      "action": "redeemCoupon",
      "entities": [
        "Referral"
      ],
      "limit": 83.66
    }
  ],
  "name": "10% off dinner for 2 at Sadhu",
  "referralRedemptionCount": 34,
  "referralSettings": {
    "couponPattern": "3vu1ofi6b0",
    "validCharacters": [
      "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
      "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
    ]
  },
  "startTime": "2018-10-15T15:39:19.949628807Z",
  "state": "enabled",
  "tags": [
    "new customer promo",
    "country"
  ],
  "updated": "2016-04-01T08:01:11Z",
  "updatedBy": "Campaign.updatedBy",
  "userId": 98
}

#Delete a Campaign

DELETE /v1/applications/{applicationId}/campaigns/{campaignId}

Parameters

applicationId integer
campaignId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97 \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#Duplicate the campaign into every specified application

POST /v1/applications/{applicationId}/campaigns/{campaignId}/campaign_duplicate

Duplicate the campaign into every specified application.

Parameters

applicationId integer
campaignId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/campaign_duplicate \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "applicationIds": [
    "CampaignDuplicate.applicationIds",
    "CampaignDuplicate.applicationIds",
    "CampaignDuplicate.applicationIds"
  ]
}'

Response (200)

{
  "data": [
    {
      "activeRulesetId": 33,
      "applicationId": 56,
      "attributes": {
        "LastOrderDate": "2016-01-16T06:39:06Z",
        "OrderCount": 78,
        "PaymentMethod": "Session payment method"
      },
      "couponRedemptionCount": 6,
      "couponSettings": {
        "couponPattern": "fz17kz3vxt",
        "validCharacters": [
          "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
          "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
        ]
      },
      "created": "2016-04-08T02:58:12Z",
      "createdBy": "Campaign.createdBy",
      "description": "description",
      "discountCount": 44,
      "endTime": "2019-03-19T15:39:19.949628807Z",
      "features": [
        "loyalty",
        "referrals",
        "referrals"
      ],
      "id": 32,
      "lastActivity": "2016-10-11T23:08:28Z",
      "limits": [
        {
          "action": "setDiscount",
          "entities": [
            "Referral"
          ],
          "limit": 46.65
        },
        {
          "action": "redeemCoupon",
          "entities": [
            "Referral"
          ],
          "limit": 83.66
        }
      ],
      "name": "10% off dinner for 2 at Sadhu",
      "referralRedemptionCount": 34,
      "referralSettings": {
        "couponPattern": "3vu1ofi6b0",
        "validCharacters": [
          "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
          "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
        ]
      },
      "startTime": "2018-10-15T15:39:19.949628807Z",
      "state": "enabled",
      "tags": [
        "new customer promo",
        "country"
      ],
      "updated": "2016-04-01T08:01:11Z",
      "updatedBy": "Campaign.updatedBy",
      "userId": 98
    }
  ]
}

#Get a list of all campaigns that match the given attributes

POST /v1/applications/{applicationId}/campaigns_search

Gets a list of all the campaigns that exactly match a set of attributes.

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
campaignState string - Filter results by the state of the campaign.

Request

curl https://example.talon.one/v1/applications/42/campaigns_search \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "attributes": {
    "FlashVersion": "Flash version"
  }
}'

Response (200)

{
  "data": [
    {
      "activeRulesetId": 33,
      "applicationId": 56,
      "attributes": {
        "LastOrderDate": "2016-01-16T06:39:06Z",
        "OrderCount": 78,
        "PaymentMethod": "Session payment method"
      },
      "couponRedemptionCount": 6,
      "couponSettings": {
        "couponPattern": "fz17kz3vxt",
        "validCharacters": [
          "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
          "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
        ]
      },
      "created": "2016-04-08T02:58:12Z",
      "createdBy": "Campaign.createdBy",
      "description": "description",
      "discountCount": 44,
      "endTime": "2019-03-19T15:39:19.949628807Z",
      "features": [
        "loyalty",
        "referrals",
        "referrals"
      ],
      "id": 32,
      "lastActivity": "2016-10-11T23:08:28Z",
      "limits": [
        {
          "action": "setDiscount",
          "entities": [
            "Referral"
          ],
          "limit": 46.65
        },
        {
          "action": "redeemCoupon",
          "entities": [
            "Referral"
          ],
          "limit": 83.66
        }
      ],
      "name": "10% off dinner for 2 at Sadhu",
      "referralRedemptionCount": 34,
      "referralSettings": {
        "couponPattern": "3vu1ofi6b0",
        "validCharacters": [
          "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
          "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
        ]
      },
      "startTime": "2018-10-15T15:39:19.949628807Z",
      "state": "enabled",
      "tags": [
        "new customer promo",
        "country"
      ],
      "updated": "2016-04-01T08:01:11Z",
      "updatedBy": "Campaign.updatedBy",
      "userId": 98
    }
  ]
}

#Create a Ruleset

POST /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets

Parameters

applicationId integer
campaignId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/rulesets \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "rbVersion": "NewRuleset.rbVersion",
  "rules": [
    {
      "bindings": [
        {
          "expression": [
            "countEvents"
          ],
          "name": "profile"
        },
        {
          "expression": [
            "setDiscount"
          ],
          "name": "foo"
        }
      ],
      "condition": [
        "=",
        2,
        [
          "countEvents",
          "profile",
          [
            "=",
            [
              ".",
              "Event",
              "Type"
            ],
            "foo"
          ]
        ]
      ],
      "description": "Create ruleset: when countEvents(type=foo, scope=profile)=2 then setDiscount(foo, 3)",
      "effects": [
        [
          "setDiscount",
          "foo",
          3
        ]
      ],
      "title": "count foo"
    }
  ]
}'

Response (201)

{
  "activatedAt": "2016-09-30T05:20:47Z",
  "campaignId": 39,
  "created": "2016-01-21T05:44:31Z",
  "id": 19,
  "rbVersion": "Ruleset...NewRuleset.rbVersion",
  "rules": [
    {
      "bindings": [
        {
          "expression": [
            "countEvents"
          ],
          "name": "profile"
        },
        {
          "expression": [
            "setDiscount"
          ],
          "name": "foo"
        }
      ],
      "condition": [
        "=",
        2,
        [
          "countEvents",
          "profile",
          [
            "=",
            [
              ".",
              "Event",
              "Type"
            ],
            "foo"
          ]
        ]
      ],
      "description": "Create ruleset: when countEvents(type=foo, scope=profile)=2 then setDiscount(foo, 3)",
      "effects": [
        [
          "setDiscount",
          "foo",
          3
        ]
      ],
      "title": "count foo"
    }
  ],
  "userId": 32
}

#List Campaign Rulesets

GET /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets

Parameters

applicationId integer
campaignId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/applications/42/campaigns/42/rulesets \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "activatedAt": "2016-09-30T05:20:47Z",
      "campaignId": 39,
      "created": "2016-01-21T05:44:31Z",
      "id": 19,
      "rbVersion": "Ruleset...NewRuleset.rbVersion",
      "rules": [
        {
          "bindings": [
            {
              "expression": [
                "countEvents"
              ],
              "name": "profile"
            },
            {
              "expression": [
                "setDiscount"
              ],
              "name": "foo"
            }
          ],
          "condition": [
            "=",
            2,
            [
              "countEvents",
              "profile",
              [
                "=",
                [
                  ".",
                  "Event",
                  "Type"
                ],
                "foo"
              ]
            ]
          ],
          "description": "Create ruleset: when countEvents(type=foo, scope=profile)=2 then setDiscount(foo, 3)",
          "effects": [
            [
              "setDiscount",
              "foo",
              3
            ]
          ],
          "title": "count foo"
        }
      ],
      "userId": 32
    }
  ]
}

#Update a Ruleset

PUT /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId}

Parameters

applicationId integer
campaignId integer
rulesetId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/rulesets/1234 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "rbVersion": "NewRuleset.rbVersion",
  "rules": [
    {
      "bindings": [
        {
          "expression": [
            "countEvents"
          ],
          "name": "profile"
        },
        {
          "expression": [
            "setDiscount"
          ],
          "name": "foo"
        }
      ],
      "condition": [
        "=",
        2,
        [
          "countEvents",
          "profile",
          [
            "=",
            [
              ".",
              "Event",
              "Type"
            ],
            "foo"
          ]
        ]
      ],
      "description": "Create ruleset: when countEvents(type=foo, scope=profile)=2 then setDiscount(foo, 3)",
      "effects": [
        [
          "setDiscount",
          "foo",
          3
        ]
      ],
      "title": "count foo"
    }
  ]
}'

Response (200)

{
  "activatedAt": "2016-09-30T05:20:47Z",
  "campaignId": 39,
  "created": "2016-01-21T05:44:31Z",
  "id": 19,
  "rbVersion": "Ruleset...NewRuleset.rbVersion",
  "rules": [
    {
      "bindings": [
        {
          "expression": [
            "countEvents"
          ],
          "name": "profile"
        },
        {
          "expression": [
            "setDiscount"
          ],
          "name": "foo"
        }
      ],
      "condition": [
        "=",
        2,
        [
          "countEvents",
          "profile",
          [
            "=",
            [
              ".",
              "Event",
              "Type"
            ],
            "foo"
          ]
        ]
      ],
      "description": "Create ruleset: when countEvents(type=foo, scope=profile)=2 then setDiscount(foo, 3)",
      "effects": [
        [
          "setDiscount",
          "foo",
          3
        ]
      ],
      "title": "count foo"
    }
  ],
  "userId": 32
}

#Get a Ruleset

GET /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId}

Parameters

applicationId integer
campaignId integer
rulesetId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/rulesets/1234 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "activatedAt": "2016-09-30T05:20:47Z",
  "campaignId": 39,
  "created": "2016-01-21T05:44:31Z",
  "id": 19,
  "rbVersion": "Ruleset...NewRuleset.rbVersion",
  "rules": [
    {
      "bindings": [
        {
          "expression": [
            "countEvents"
          ],
          "name": "profile"
        },
        {
          "expression": [
            "setDiscount"
          ],
          "name": "foo"
        }
      ],
      "condition": [
        "=",
        2,
        [
          "countEvents",
          "profile",
          [
            "=",
            [
              ".",
              "Event",
              "Type"
            ],
            "foo"
          ]
        ]
      ],
      "description": "Create ruleset: when countEvents(type=foo, scope=profile)=2 then setDiscount(foo, 3)",
      "effects": [
        [
          "setDiscount",
          "foo",
          3
        ]
      ],
      "title": "count foo"
    }
  ],
  "userId": 32
}

#Delete a Ruleset

DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId}

Parameters

applicationId integer
campaignId integer
rulesetId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/rulesets/1234 \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#Coupons

Coupons are unique codes belonging to a particular campaign. They don't define any behaviour on their own, instead the campaign ruleset can include rules that validate coupons and carry out particular effects.

#Create Coupons

POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons

Create coupons according to some pattern. Up to 20.000 coupons can be created without a unique prefix. When a unique prefix is provided, up to 200.000 coupns can be created.

Parameters

applicationId integer
campaignId integer

Query Parameters

silent string - If set to 'yes', response will be an empty 204, otherwise a list of the coupons generated (to to 1000).

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/coupons \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "attributes": {
    "DestinationStation": "Travel destination station",
    "FrequentFlyerPoints": 34,
    "FrequentFlyerStatus": "Frequent flyer status",
    "ShippingSalutation": "Session shipping salutation"
  },
  "couponPattern": "yld6611o3t",
  "expiryDate": "2018-12-29T15:39:19.949628807Z",
  "numberOfCoupons": 88,
  "recipientIntegrationId": "42",
  "startDate": "2018-10-15T15:39:19.949628807Z",
  "uniquePrefix": "NewCoupons.uniquePrefix",
  "usageLimit": 50,
  "validCharacters": [
    "A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z",
    "0, 1, 2, 3, 4, 5, 6, 7, 8, 9"
  ]
}'

Response (200)

{
  "data": [
    {
      "attributes": {
        "SessionDuration": "2016-06-03T20:02:43Z"
      },
      "batchId": "Coupon.batchId",
      "campaignId": 26,
      "created": "2016-02-03T22:20:27Z",
      "expiryDate": "2019-01-20T15:39:19.949628807Z",
      "id": 89,
      "importId": 93,
      "recipientIntegrationId": "87",
      "referralId": 84,
      "startDate": "2018-10-15T15:39:19.949628807Z",
      "usageCounter": 83,
      "usageLimit": 0,
      "value": "7pzg8spy6x"
    }
  ]
}

#List Coupons

GET /v1/applications/{applicationId}/campaigns/{campaignId}/coupons

Parameters

applicationId integer
campaignId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
value string - Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
createdBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
createdAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
startsAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
startsBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
expiresAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
expiresBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
valid string - Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.
batchId string - Filter results by batches of coupons
usable string - Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
referralId integer - Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.
recipientIntegrationId string - Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field
exactMatch bool - Filter results to an exact case-insensitive matching against the coupon code

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/coupons \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "attributes": {
        "SessionDuration": "2016-06-03T20:02:43Z"
      },
      "batchId": "Coupon.batchId",
      "campaignId": 26,
      "created": "2016-02-03T22:20:27Z",
      "expiryDate": "2019-01-20T15:39:19.949628807Z",
      "id": 89,
      "importId": 93,
      "recipientIntegrationId": "87",
      "referralId": 84,
      "startDate": "2018-10-15T15:39:19.949628807Z",
      "usageCounter": 83,
      "usageLimit": 0,
      "value": "7pzg8spy6x"
    }
  ]
}

#Delete Coupons

DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/coupons

Parameters

applicationId integer
campaignId integer

Query Parameters

value string - Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
createdBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
createdAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
startsAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
startsBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
expiresAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
expiresBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
valid string - Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.
batchId string - Filter results by batches of coupons
usable string - Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
referralId integer - Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.
recipientIntegrationId string - Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field
exactMatch bool - Filter results to an exact case-insensitive matching against the coupon code

Request

curl https://example.talon.one/v1/applications/42/campaigns/42/coupons \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#List Coupons

GET /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/no_total

Parameters

applicationId integer
campaignId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
value string - Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
createdBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
createdAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
valid string - Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.
usable string - Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
referralId integer - Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.
recipientIntegrationId string - Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field
batchId string - Filter results by batches of coupons
exactMatch bool - Filter results to an exact case-insensitive matching against the coupon code

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/coupons/no_total \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "attributes": {
        "SessionDuration": "2016-06-03T20:02:43Z"
      },
      "batchId": "Coupon.batchId",
      "campaignId": 26,
      "created": "2016-02-03T22:20:27Z",
      "expiryDate": "2019-01-20T15:39:19.949628807Z",
      "id": 89,
      "importId": 93,
      "recipientIntegrationId": "87",
      "referralId": 84,
      "startDate": "2018-10-15T15:39:19.949628807Z",
      "usageCounter": 83,
      "usageLimit": 0,
      "value": "7pzg8spy6x"
    }
  ]
}

#Update a Coupon

PUT /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId}

Parameters

applicationId integer
campaignId integer
couponId string - The ID of the coupon code to update

Request

curl https://example.talon.one/v1/applications/42/campaigns/42/coupons/42 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "attributes": {
    "DepartureCity": "Departure city",
    "DepartureCountry": "Departure country",
    "PageVisitedProfile": "Page ever visited",
    "ShippingName": "Default shipping name"
  },
  "expiryDate": "2019-02-03T15:39:19.949628807Z",
  "recipientIntegrationId": "37",
  "startDate": "2018-10-15T15:39:19.949628807Z",
  "usageLimit": 78,
  "value": "6t8ntgw8nf"
}'

Response (200)

{
  "attributes": {
    "SessionDuration": "2016-06-03T20:02:43Z"
  },
  "batchId": "Coupon.batchId",
  "campaignId": 26,
  "created": "2016-02-03T22:20:27Z",
  "expiryDate": "2019-01-20T15:39:19.949628807Z",
  "id": 89,
  "importId": 93,
  "recipientIntegrationId": "87",
  "referralId": 84,
  "startDate": "2018-10-15T15:39:19.949628807Z",
  "usageCounter": 83,
  "usageLimit": 0,
  "value": "7pzg8spy6x"
}

#Delete one Coupon

DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId}

Parameters

applicationId integer
campaignId integer
couponId string - The ID of the coupon code to delete

Request

curl https://example.talon.one/v1/applications/42/campaigns/42/coupons/42 \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#Get a list of the coupons that match the given attributes

POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search

Gets a list of all the coupons that exactly match a set of attributes.

The match is successful if all the attributes of the request are found in a coupon, even if the coupon has more attributes that are not present on the request.

Parameters

applicationId integer
campaignId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
value string - Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
createdBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
createdAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
valid string - Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.
usable string - Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
referralId integer - Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.
recipientIntegrationId string - Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field
exactMatch bool - Filter results to an exact case-insensitive matching against the coupon code
batchId string - Filter results by batches of coupons

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/coupons_search \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "attributes": {
    "BaggagePieces": 52,
    "DepartureStation": "Travel departure station",
    "SignupDate": "2016-10-09T16:28:51Z"
  }
}'

Response (200)

{
  "data": [
    {
      "attributes": {
        "SessionDuration": "2016-06-03T20:02:43Z"
      },
      "batchId": "Coupon.batchId",
      "campaignId": 26,
      "created": "2016-02-03T22:20:27Z",
      "expiryDate": "2019-01-20T15:39:19.949628807Z",
      "id": 89,
      "importId": 93,
      "recipientIntegrationId": "87",
      "referralId": 84,
      "startDate": "2018-10-15T15:39:19.949628807Z",
      "usageCounter": 83,
      "usageLimit": 0,
      "value": "7pzg8spy6x"
    }
  ]
}

#Get a list of the coupons that match the given attributes in all active campaigns of an application

POST /v1/applications/{applicationId}/coupons_search

Gets a list of all the coupons with attributes matching the query criteria Application wide

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
value string - Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
createdBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
createdAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
valid string - Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.
usable string - Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
referralId integer - Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.
recipientIntegrationId string - Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field
batchId string - Filter results by batches of coupons
exactMatch bool - Filter results to an exact case-insensitive matching against the coupon code
campaignState string - Filter results by the state of the campaign.

Request

curl https://example.talon.one/v1/applications/42/coupons_search \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "attributes": {
    "BaggagePieces": 52,
    "DepartureStation": "Travel departure station",
    "SignupDate": "2016-10-09T16:28:51Z"
  }
}'

Response (200)

{
  "data": [
    {
      "attributes": {
        "SessionDuration": "2016-06-03T20:02:43Z"
      },
      "batchId": "Coupon.batchId",
      "campaignId": 26,
      "created": "2016-02-03T22:20:27Z",
      "expiryDate": "2019-01-20T15:39:19.949628807Z",
      "id": 89,
      "importId": 93,
      "recipientIntegrationId": "87",
      "referralId": 84,
      "startDate": "2018-10-15T15:39:19.949628807Z",
      "usageCounter": 83,
      "usageLimit": 0,
      "value": "7pzg8spy6x"
    }
  ]
}

#Get a list of the coupons that match the given attributes

POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search_advanced

Gets a list of all the coupons with attributes matching the query criteria

Parameters

applicationId integer
campaignId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
value string - Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
createdBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
createdAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
valid string - Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.
usable string - Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
referralId integer - Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.
recipientIntegrationId string - Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field
exactMatch bool - Filter results to an exact case-insensitive matching against the coupon code
batchId string - Filter results by batches of coupons

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/coupons_search_advanced \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{}'

Response (200)

{
  "data": [
    {
      "attributes": {
        "SessionDuration": "2016-06-03T20:02:43Z"
      },
      "batchId": "Coupon.batchId",
      "campaignId": 26,
      "created": "2016-02-03T22:20:27Z",
      "expiryDate": "2019-01-20T15:39:19.949628807Z",
      "id": 89,
      "importId": 93,
      "recipientIntegrationId": "87",
      "referralId": 84,
      "startDate": "2018-10-15T15:39:19.949628807Z",
      "usageCounter": 83,
      "usageLimit": 0,
      "value": "7pzg8spy6x"
    }
  ]
}

#Get a list of the coupons that match the given attributes in all active campaigns of an application

POST /v1/applications/{applicationId}/coupons_search_advanced

Gets a list of all the coupons with attributes matching the query criteria in all active campaigns of an application

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
value string - Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
createdBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
createdAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
valid string - Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.
usable string - Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
referralId integer - Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.
recipientIntegrationId string - Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field
batchId string - Filter results by batches of coupons
exactMatch bool - Filter results to an exact case-insensitive matching against the coupon code
campaignState string - Filter results by the state of the campaign.

Request

curl https://example.talon.one/v1/applications/42/coupons_search_advanced \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{}'

Response (200)

{
  "data": [
    {
      "attributes": {
        "SessionDuration": "2016-06-03T20:02:43Z"
      },
      "batchId": "Coupon.batchId",
      "campaignId": 26,
      "created": "2016-02-03T22:20:27Z",
      "expiryDate": "2019-01-20T15:39:19.949628807Z",
      "id": 89,
      "importId": 93,
      "recipientIntegrationId": "87",
      "referralId": 84,
      "startDate": "2018-10-15T15:39:19.949628807Z",
      "usageCounter": 83,
      "usageLimit": 0,
      "value": "7pzg8spy6x"
    }
  ]
}

#Import coupons via CSV file.

POST /v1/applications/{applicationId}/campaigns/{campaignId}/import_coupons

"Upload a CSV file containing the coupons that should be created. The file should be sent as multipart data."

Parameters

applicationId integer - The identifier for the application
campaignId integer

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/import_coupons \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "accountId": 20,
  "created": "2016-04-13T20:26:38Z",
  "entity": "Coupon",
  "filter": {},
  "id": 91,
  "userId": 81
}

#Export Coupons to a CSV file.

GET /v1/applications/{applicationId}/export_coupons

Download a file with the coupons that match the given attributes.

Parameters

applicationId integer - The identifier for the application

Query Parameters

campaignId int - Filter results by campaign.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
value string - Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
createdBefore string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
createdAfter string - Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp.
valid string - Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiry date is set and in the past. The second matches coupons in which start date is null or in the past and expiry date is null or in the future, the third matches coupons in which start date is set and in the future.
usable string - Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
referralId integer - Filter the results by matching them with the Id of a referral, that meaning the coupons that had been created as an effect of the usage of a referral code.
recipientIntegrationId string - Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field
batchId string - Filter results by batches of coupons
exactMatch bool - Filter results to an exact case-insensitive matching against the coupon code
dateFormat string - Determines the format of dates in the export document.
campaignState string - Filter results by the state of the campaign.

Request

curl https://example.talon.one/v1/applications/42/export_coupons \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{}

#Campaign Analytics

Campaign Analytics are used to retrieve statistical data about the performance of a specific campaign.

#Get analytics of campaigns

GET /v1/applications/{applicationId}/campaigns/{campaignId}/analytics

Parameters

applicationId integer - The identifier for the application
campaignId integer

Query Parameters

rangeStart string (required) - Only return results from after this timestamp, must be an RFC3339 timestamp string
rangeEnd string (required) - Only return results from before this timestamp, must be an RFC3339 timestamp string
granularity string - The time interval between the results in the returned time-series.

Request

curl https://example.talon.one/v1/applications/42/campaigns/97/analytics \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "campaignDiscountCosts": 35.59,
      "campaignRevenue": 72.56,
      "couponRedemptions": 42,
      "couponsCreated": 10,
      "date": "2016-04-25T09:06:51Z",
      "totalCampaignDiscountCosts": 20.8,
      "totalCampaignRevenue": 12.2,
      "totalCouponRedemptions": 67,
      "totalCouponsCreated": 26
    }
  ]
}

#Customer Data

Customer Data operations are used to retrieve data about customers/sessions/events for reporting and debugging in the Campaign Manager.

#List Application Customers

GET /v1/applications/{applicationId}/customers

Parameters

applicationId integer

Request

curl https://example.talon.one/v1/applications/42/customers \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "accountId": 69,
      "attributes": {
        "Language": "Language",
        "OperatingSystem": "Operating System",
        "VenueId": "Venue ID"
      },
      "closedSessions": 91,
      "created": "2016-06-23T00:41:31Z",
      "id": 17,
      "integrationId": "NewCustomerProfile69",
      "lastActivity": "2016-03-03T10:34:27Z",
      "loyaltyMemberships": [
        {
          "joined": "2016-04-01T05:07:53Z",
          "loyaltyProgramId": 45
        },
        {
          "joined": "2016-07-02T00:19:27Z",
          "loyaltyProgramId": 42
        },
        {
          "joined": "2016-03-01T10:46:07Z",
          "loyaltyProgramId": 17
        },
        {
          "joined": "2016-08-07T22:43:20Z",
          "loyaltyProgramId": 57
        }
      ],
      "totalSales": 43.16
    }
  ]
}

#Get a list of the customer profiles that match the given attributes

POST /v1/application_customer_search

Gets a list of all the cusomer profiles for the account that exactly match a set of attributes.

The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.

Request

curl https://example.talon.one/v1/application_customer_search \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "attributes": {
    "BillingSalutation": "Default Billing salutation",
    "SessionCount": 27,
    "ShippingAddress1": "Session shipping address field 1",
    "ShippingAddress3": "Session shipping address field 3"
  },
  "integrationIDs": [],
  "profileIDs": []
}'

Response (200)

{
  "data": [
    {
      "accountId": 69,
      "attributes": {
        "Language": "Language",
        "OperatingSystem": "Operating System",
        "VenueId": "Venue ID"
      },
      "closedSessions": 91,
      "created": "2016-06-23T00:41:31Z",
      "id": 17,
      "integrationId": "NewCustomerProfile69",
      "lastActivity": "2016-03-03T10:34:27Z",
      "loyaltyMemberships": [
        {
          "joined": "2016-04-01T05:07:53Z",
          "loyaltyProgramId": 45
        },
        {
          "joined": "2016-07-02T00:19:27Z",
          "loyaltyProgramId": 42
        },
        {
          "joined": "2016-03-01T10:46:07Z",
          "loyaltyProgramId": 17
        },
        {
          "joined": "2016-08-07T22:43:20Z",
          "loyaltyProgramId": 57
        }
      ],
      "totalSales": 43.16
    }
  ]
}

#Get Application Customer

GET /v1/applications/{applicationId}/customers/{customerId}

Parameters

applicationId integer
customerId integer

Request

curl https://example.talon.one/v1/applications/42/customers/42 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "accountId": 69,
  "attributes": {
    "Language": "Language",
    "OperatingSystem": "Operating System",
    "VenueId": "Venue ID"
  },
  "closedSessions": 91,
  "created": "2016-06-23T00:41:31Z",
  "id": 17,
  "integrationId": "NewCustomerProfile69",
  "lastActivity": "2016-03-03T10:34:27Z",
  "loyaltyMemberships": [
    {
      "joined": "2016-04-01T05:07:53Z",
      "loyaltyProgramId": 45
    },
    {
      "joined": "2016-07-02T00:19:27Z",
      "loyaltyProgramId": 42
    },
    {
      "joined": "2016-03-01T10:46:07Z",
      "loyaltyProgramId": 17
    },
    {
      "joined": "2016-08-07T22:43:20Z",
      "loyaltyProgramId": 57
    }
  ],
  "totalSales": 43.16
}

#Get Activity Reports for Application Customers

GET /v1/applications/{applicationId}/customer_activity_reports

Fetch summary reports for all application customers based on a time range

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
rangeStart string (required) - Only return results from after this timestamp, must be an RFC3339 timestamp string
rangeEnd string (required) - Only return results from before this timestamp, must be an RFC3339 timestamp string
name string - Only return reports matching the customer name
integrationId string - Only return reports matching the integrationId
campaignName string - Only return reports matching the campaignName
advocateName string - Only return reports matching the current customer referrer name

Request

curl https://example.talon.one/v1/applications/42/customer_activity_reports \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "accruedDiscounts": 9.31,
      "accruedRevenue": 74.09,
      "campaignName": "CustomerActivityReport.campaignName",
      "couponFailedAttempts": 65,
      "couponRedemptions": 27,
      "couponUseAttempts": 62,
      "created": "2016-11-08T07:48:39Z",
      "customerId": 3,
      "integrationId": "NewCustomerProfile69",
      "lastActivity": "2016-06-06T23:08:46Z",
      "name": "Katelyn Nolan",
      "totalOrders": 64,
      "totalOrdersNoCoupon": 77
    }
  ]
}

#Get Activity Reports for Application Customers

GET /v1/applications/{applicationId}/customer_activity_reports/no_total

Fetch summary reports for all application customers based on a time range. Instead of having the total number of results in the response, this endpoint only if there are more results.

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
rangeStart string (required) - Only return results from after this timestamp, must be an RFC3339 timestamp string
rangeEnd string (required) - Only return results from before this timestamp, must be an RFC3339 timestamp string
name string - Only return reports matching the customer name
integrationId string - Only return reports matching the integrationId
campaignName string - Only return reports matching the campaignName
advocateName string - Only return reports matching the current customer referrer name

Request

curl https://example.talon.one/v1/applications/42/customer_activity_reports/no_total \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "accruedDiscounts": 9.31,
      "accruedRevenue": 74.09,
      "campaignName": "CustomerActivityReport.campaignName",
      "couponFailedAttempts": 65,
      "couponRedemptions": 27,
      "couponUseAttempts": 62,
      "created": "2016-11-08T07:48:39Z",
      "customerId": 3,
      "integrationId": "NewCustomerProfile69",
      "lastActivity": "2016-06-06T23:08:46Z",
      "name": "Katelyn Nolan",
      "totalOrders": 64,
      "totalOrdersNoCoupon": 77
    }
  ]
}

#Get Activity Report for Single Customer

GET /v1/applications/{applicationId}/customer_activity_reports/{customerId}

Fetch summary report for single application customer based on a time range

Parameters

applicationId integer
customerId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
rangeStart string (required) - Only return results from after this timestamp, must be an RFC3339 timestamp string
rangeEnd string (required) - Only return results from before this timestamp, must be an RFC3339 timestamp string

Request

curl https://example.talon.one/v1/applications/42/customer_activity_reports/42 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "accruedDiscounts": 9.31,
  "accruedRevenue": 74.09,
  "campaignName": "CustomerActivityReport.campaignName",
  "couponFailedAttempts": 65,
  "couponRedemptions": 27,
  "couponUseAttempts": 62,
  "created": "2016-11-08T07:48:39Z",
  "customerId": 3,
  "integrationId": "NewCustomerProfile69",
  "lastActivity": "2016-06-06T23:08:46Z",
  "name": "Katelyn Nolan",
  "totalOrders": 64,
  "totalOrdersNoCoupon": 77
}

#List Application Sessions

GET /v1/applications/{applicationId}/sessions

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
profile string - Profile integration ID filter for sessions. Must be exact match.

Request

curl https://example.talon.one/v1/applications/42/sessions \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "applicationId": 12,
      "attributes": {
        "AdditionalEmails": "Additional Emails"
      },
      "cartItems": [],
      "coupon": "w34f410t08",
      "created": "2016-02-05T20:04:31Z",
      "discounts": {
        "cheapest item": 5,
        "coupon": 7
      },
      "id": 48,
      "integrationId": "NewCustomerProfile69",
      "profileId": 82,
      "referral": "hfltixp8ow",
      "state": "cancelled"
    }
  ]
}

#Get Application Session

GET /v1/applications/{applicationId}/sessions/{sessionId}

Parameters

applicationId integer
sessionId integer

Request

curl https://example.talon.one/v1/applications/42/sessions/42 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "applicationId": 12,
  "attributes": {
    "AdditionalEmails": "Additional Emails"
  },
  "cartItems": [],
  "coupon": "w34f410t08",
  "created": "2016-02-05T20:04:31Z",
  "discounts": {
    "cheapest item": 5,
    "coupon": 7
  },
  "id": 48,
  "integrationId": "NewCustomerProfile69",
  "profileId": 82,
  "referral": "hfltixp8ow",
  "state": "cancelled"
}

#List Applications Events

GET /v1/applications/{applicationId}/events

Lists all events recorded for an application.

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
type string - Comma-separated list of types by which to filter events. Must be exact match(es).
createdBefore string - Only return events created before this date
createdAfter string - Only return events created after this date
session string - Session integration ID filter for events. Must be exact match.
profile string - Profile integration ID filter for events. Must be exact match.
customerName string - Customer name filter for events. Will match substrings case-insensitively.
customerEmail string - Customer e-mail address filter for events. Will match substrings case-insensitively.
effectsQuery string - Effects filter for events. Will perform a full-text search on the text content of the events effects, if any.
attributesQuery string - Attributes filter for events. Will perform a full-text search on the text content of the events attributes, both keys and values.
ruleQuery string - Rule name filter for events
campaignQuery string - Campaign name filter for events

Request

curl https://example.talon.one/v1/applications/42/events \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "applicationId": 72,
      "attributes": {
        "DepartureCity": "Departure city",
        "ShippingCity": "Session shipping city",
        "ShippingMethod": "Session shipping method",
        "URL": "Customer's URL"
      },
      "created": "2016-09-11T17:58:57Z",
      "effects": [
        "createApplication",
        "put",
        "setDiscount"
      ],
      "id": 71,
      "profileId": 96,
      "sessionId": 76,
      "type": "talon_session_updated"
    }
  ]
}

#List Applications Events

GET /v1/applications/{applicationId}/events/no_total

Lists all events recorded for an application. Instead of having the total number of results in the response, this endpoint only if there are more results.

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
type string - Comma-separated list of types by which to filter events. Must be exact match(es).
createdBefore string - Only return events created before this date
createdAfter string - Only return events created after this date
session string - Session integration ID filter for events. Must be exact match.
profile string - Profile integration ID filter for events. Must be exact match.
customerName string - Customer name filter for events. Will match substrings case-insensitively.
customerEmail string - Customer e-mail address filter for events. Will match substrings case-insensitively.
effectsQuery string - Effects filter for events. Will perform a full-text search on the text content of the events effects, if any.
attributesQuery string - Attributes filter for events. Will perform a full-text search on the text content of the events attributes, both keys and values.
ruleQuery string - Rule name filter for events
campaignQuery string - Campaign name filter for events

Request

curl https://example.talon.one/v1/applications/42/events/no_total \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "applicationId": 72,
      "attributes": {
        "DepartureCity": "Departure city",
        "ShippingCity": "Session shipping city",
        "ShippingMethod": "Session shipping method",
        "URL": "Customer's URL"
      },
      "created": "2016-09-11T17:58:57Z",
      "effects": [
        "createApplication",
        "put",
        "setDiscount"
      ],
      "id": 71,
      "profileId": 96,
      "sessionId": 76,
      "type": "talon_session_updated"
    }
  ]
}

#List Applications Event Types

GET /v1/applications/{applicationId}/event_types

Get all of the distinct values of the Event type property for events recorded in the application.

See also: Track an event

Parameters

applicationId integer

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/applications/42/event_types \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    "ApplicationEventType"
  ]
}

#Customization

Talon.One is extremely customizable. These API operations allow you to alter the data model and rule builder to better suit Talon.One to the needs of your business.

#Get Talang Environment

GET /v1/applications/{applicationId}/talang_environment

Parameters

applicationId integer

Request

curl https://example.talon.one/v1/applications/42/talang_environment \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{}

#Update a custom Talang template

PUT /v1/applications/{applicationId}/talang_templates/{name}

This operation allows developers to create & update custom templates for rules, conditions, and effects. These custom templates are available to campaign managers in the sidebar of the campaign rule editor.

Parameters

applicationId integer
name string - The name of the template. This is used in the Talang expressions of rules.

Request

curl https://example.talon.one/v1/applications/42/talang_templates/42 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d 'undefined'

Response (200)

{}

#Delete a custom Talang template

DELETE /v1/applications/{applicationId}/talang_templates/{name}

Delete a custom Talang template. Warning: this operation does not check if the template is in use by any rules.

Parameters

applicationId integer
name string - The name of the template. This is used in the Talang expressions of rules.

Request

curl https://example.talon.one/v1/applications/42/talang_templates/42 \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#Get the library of attributes

GET /v1/attributes_library

Returns all the attributes in the library

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/attributes_library \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "description": "Alternative invoice address for a session: 3rd address field.",
      "entity": "CustomerSession",
      "name": "BillingAddress3",
      "presets": [
        "User"
      ],
      "tags": [],
      "title": "Session billing address field 3",
      "type": "string"
    }
  ]
}

#Define a new custom attribute

POST /v1/attributes

Defines a new custom attribute in this account. Custom attributes allow you to attach new fields to Talon.One domain objects like campaigns, coupons, customers and so on. These attributes can then be given values when creating / updating these objects, and these values can be used in your campaign rules. For example, you could define a zipCode field for customer sessions, and add a rule to your campaign that only allows certain ZIP codes.

These attributes are shared across all applications in your account, and are never required.

Request

curl https://example.talon.one/v1/attributes \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "description": "description",
  "editable": false,
  "entity": "CustomerSession",
  "eventType": "NewAttribute.eventType",
  "name": "new attribute Talang call",
  "suggestions": [
    "NewAttribute.suggestions",
    "NewAttribute.suggestions",
    "NewAttribute.suggestions"
  ],
  "tags": [
    "new customer promo",
    "country"
  ],
  "title": "new attribute name",
  "type": "number"
}'

Response (201)

{
  "accountId": 22,
  "created": "2016-01-06T18:59:47Z",
  "description": "description",
  "editable": false,
  "entity": "CartItem",
  "eventType": "Attribute...NewAttribute.eventType",
  "id": 94,
  "lastUsed": "2016-08-09T03:08:28Z",
  "lastUsedApplicationId": 12,
  "lastUsedRequestUuid": "12bc69983dcd4f028bf11f9d65a689ce",
  "locked": true,
  "modified": "2016-07-07T05:04:58Z",
  "name": "new attribute Talang call",
  "suggestions": [
    "Attribute...NewAttribute.suggestions",
    "Attribute...NewAttribute.suggestions",
    "Attribute...NewAttribute.suggestions"
  ],
  "tags": [
    "new customer promo",
    "country"
  ],
  "title": "new attribute name",
  "type": "time",
  "usedAt": []
}

#List custom attributes

GET /v1/attributes

Returns all the defined custom attributes for the account.

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/attributes \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "accountId": 22,
      "created": "2016-01-06T18:59:47Z",
      "description": "description",
      "editable": false,
      "entity": "CartItem",
      "eventType": "Attribute...NewAttribute.eventType",
      "id": 94,
      "lastUsed": "2016-08-09T03:08:28Z",
      "lastUsedApplicationId": 12,
      "lastUsedRequestUuid": "12bc69983dcd4f028bf11f9d65a689ce",
      "locked": true,
      "modified": "2016-07-07T05:04:58Z",
      "name": "new attribute Talang call",
      "suggestions": [
        "Attribute...NewAttribute.suggestions",
        "Attribute...NewAttribute.suggestions",
        "Attribute...NewAttribute.suggestions"
      ],
      "tags": [
        "new customer promo",
        "country"
      ],
      "title": "new attribute name",
      "type": "time",
      "usedAt": []
    }
  ]
}

#Get a custom attribute

GET /v1/attributes/{attributeId}

Returns custom attribute for the account by its id.

Parameters

attributeId integer

Request

curl https://example.talon.one/v1/attributes/42 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "accountId": 22,
  "created": "2016-01-06T18:59:47Z",
  "description": "description",
  "editable": false,
  "entity": "CartItem",
  "eventType": "Attribute...NewAttribute.eventType",
  "id": 94,
  "lastUsed": "2016-08-09T03:08:28Z",
  "lastUsedApplicationId": 12,
  "lastUsedRequestUuid": "12bc69983dcd4f028bf11f9d65a689ce",
  "locked": true,
  "modified": "2016-07-07T05:04:58Z",
  "name": "new attribute Talang call",
  "suggestions": [
    "Attribute...NewAttribute.suggestions",
    "Attribute...NewAttribute.suggestions",
    "Attribute...NewAttribute.suggestions"
  ],
  "tags": [
    "new customer promo",
    "country"
  ],
  "title": "new attribute name",
  "type": "time",
  "usedAt": []
}

#Update a custom attribute

PUT /v1/attributes/{attributeId}

Updates an existing custom attribute. Once created, the only property of a custom attribute that can be changed is the title (human readable description). This restriction is in place to prevent accidentally breaking live integrations. E.g. if you have a customer profile attribute with the name region, and your integration is sending attributes.region with customer profile updates, changing the name to locale would cause the integration requests to begin failing.

If you really need to change the type or name property of a custom attribute, create a new attribute and update any relevant integrations and rules to use the new attribute. Then delete the old attribute when you are confident you have migrated any needed data from the old attribute to the new one.

Parameters

attributeId integer

Request

curl https://example.talon.one/v1/attributes/42 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "description": "description",
  "editable": false,
  "entity": "CustomerSession",
  "eventType": "NewAttribute.eventType",
  "name": "new attribute Talang call",
  "suggestions": [
    "NewAttribute.suggestions",
    "NewAttribute.suggestions",
    "NewAttribute.suggestions"
  ],
  "tags": [
    "new customer promo",
    "country"
  ],
  "title": "new attribute name",
  "type": "number"
}'

Response (200)

{
  "accountId": 22,
  "created": "2016-01-06T18:59:47Z",
  "description": "description",
  "editable": false,
  "entity": "CartItem",
  "eventType": "Attribute...NewAttribute.eventType",
  "id": 94,
  "lastUsed": "2016-08-09T03:08:28Z",
  "lastUsedApplicationId": 12,
  "lastUsedRequestUuid": "12bc69983dcd4f028bf11f9d65a689ce",
  "locked": true,
  "modified": "2016-07-07T05:04:58Z",
  "name": "new attribute Talang call",
  "suggestions": [
    "Attribute...NewAttribute.suggestions",
    "Attribute...NewAttribute.suggestions",
    "Attribute...NewAttribute.suggestions"
  ],
  "tags": [
    "new customer promo",
    "country"
  ],
  "title": "new attribute name",
  "type": "time",
  "usedAt": []
}

#Delete a custom attribute

DELETE /v1/attributes/{attributeId}

Removes a defined custom attribute.

Warning: this will also destroy all data associated with the attribute!

Parameters

attributeId integer

Request

curl https://example.talon.one/v1/attributes/42 \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#List Webhooks

GET /v1/webhooks

Query Parameters

applicationIds string - Filter by one or more application ids separated by comma
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.

Request

curl https://example.talon.one/v1/webhooks \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "applicationIds": [],
      "created": "2016-05-14T08:09:16Z",
      "enabled": false,
      "headers": [
        "Content-Type",
        "Content-Signature"
      ],
      "id": 45,
      "modified": "2016-10-09T14:23:38Z",
      "params": [
        {
          "description": "description",
          "title": "Webhook...NewWebhook.params...TemplateArgDef.title",
          "type": "time",
          "ui": {}
        }
      ],
      "payload": "{Name: ${$Profile.Attributes.Name}, Email: ${$Profile.Attributes.Email}}",
      "title": "Thank-you-Email",
      "url": "http://batz.org/kristy.glover",
      "usedAt": [
        "Webhook.usedAt"
      ],
      "verb": "PATCH"
    }
  ]
}

#Create Webhook

POST /v1/webhooks

Creates a new webhook.

Request

curl https://example.talon.one/v1/webhooks \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "applicationIds": [
    8
  ],
  "enabled": false,
  "headers": [
    "Content-Type",
    "Content-Signature"
  ],
  "params": [
    {
      "description": "description",
      "title": "NewWebhook.params...TemplateArgDef.title",
      "type": "time",
      "ui": {}
    }
  ],
  "payload": "{Name: ${$Profile.Attributes.Name}, Email: ${$Profile.Attributes.Email}}",
  "title": "Thank-you-Email",
  "url": "http://batz.org/kristy.glover",
  "verb": "PUT"
}'

Response (200)

{
  "applicationIds": [],
  "created": "2016-05-14T08:09:16Z",
  "enabled": false,
  "headers": [
    "Content-Type",
    "Content-Signature"
  ],
  "id": 45,
  "modified": "2016-10-09T14:23:38Z",
  "params": [
    {
      "description": "description",
      "title": "Webhook...NewWebhook.params...TemplateArgDef.title",
      "type": "time",
      "ui": {}
    }
  ],
  "payload": "{Name: ${$Profile.Attributes.Name}, Email: ${$Profile.Attributes.Email}}",
  "title": "Thank-you-Email",
  "url": "http://batz.org/kristy.glover",
  "usedAt": [
    "Webhook.usedAt"
  ],
  "verb": "PATCH"
}

#Get Webhook

GET /v1/webhooks/{webhookId}

Returns an webhook by its id.

Parameters

webhookId integer

Request

curl https://example.talon.one/v1/webhooks/42 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "applicationIds": [],
  "created": "2016-05-14T08:09:16Z",
  "enabled": false,
  "headers": [
    "Content-Type",
    "Content-Signature"
  ],
  "id": 45,
  "modified": "2016-10-09T14:23:38Z",
  "params": [
    {
      "description": "description",
      "title": "Webhook...NewWebhook.params...TemplateArgDef.title",
      "type": "time",
      "ui": {}
    }
  ],
  "payload": "{Name: ${$Profile.Attributes.Name}, Email: ${$Profile.Attributes.Email}}",
  "title": "Thank-you-Email",
  "url": "http://batz.org/kristy.glover",
  "usedAt": [
    "Webhook.usedAt"
  ],
  "verb": "PATCH"
}

#Update Webhook

PUT /v1/webhooks/{webhookId}

Updates an existing webhook.

Parameters

webhookId integer

Request

curl https://example.talon.one/v1/webhooks/42 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "applicationIds": [],
  "created": "2016-05-14T08:09:16Z",
  "enabled": false,
  "headers": [
    "Content-Type",
    "Content-Signature"
  ],
  "id": 45,
  "modified": "2016-10-09T14:23:38Z",
  "params": [
    {
      "description": "description",
      "title": "Webhook...NewWebhook.params...TemplateArgDef.title",
      "type": "time",
      "ui": {}
    }
  ],
  "payload": "{Name: ${$Profile.Attributes.Name}, Email: ${$Profile.Attributes.Email}}",
  "title": "Thank-you-Email",
  "url": "http://batz.org/kristy.glover",
  "usedAt": [
    "Webhook.usedAt"
  ],
  "verb": "PATCH"
}'

Response (200)

{
  "applicationIds": [],
  "created": "2016-05-14T08:09:16Z",
  "enabled": false,
  "headers": [
    "Content-Type",
    "Content-Signature"
  ],
  "id": 45,
  "modified": "2016-10-09T14:23:38Z",
  "params": [
    {
      "description": "description",
      "title": "Webhook...NewWebhook.params...TemplateArgDef.title",
      "type": "time",
      "ui": {}
    }
  ],
  "payload": "{Name: ${$Profile.Attributes.Name}, Email: ${$Profile.Attributes.Email}}",
  "title": "Thank-you-Email",
  "url": "http://batz.org/kristy.glover",
  "usedAt": [
    "Webhook.usedAt"
  ],
  "verb": "PATCH"
}

#Delete Webhook

DELETE /v1/webhooks/{webhookId}

Removes an existing webhook.

Parameters

webhookId integer

Request

curl https://example.talon.one/v1/webhooks/42 \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#Logs

The Talon.One API records all incoming and outgoing requests. These API operations allow you to query those logs.

#Get access logs for application

GET /v1/applications/{applicationId}/access_logs

Parameters

applicationId integer

Query Parameters

path string - Only return results where the request path matches the given regular expresssion.
method string - Only return results where the request method matches the given regular expresssion.
status string - Filter results by HTTP status codes.
rangeStart string (required) - Only return results from after this timestamp, must be an RFC3339 timestamp string
rangeEnd string (required) - Only return results from before this timestamp, must be an RFC3339 timestamp string
pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/applications/42/access_logs \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "method": "POST",
      "requestPayload": "information in a payload sent with a request",
      "requestUri": "https://robelaltenwerth.net/",
      "responsePayload": "information in a payload sent with a response",
      "status": 94,
      "time": "2016-11-03T04:28:37Z",
      "uuid": "e98d2238b20b400a94efd0b7d51d97de"
    }
  ]
}

#Get access logs for application

GET /v1/applications/{applicationId}/access_logs/no_total

Parameters

applicationId integer

Query Parameters

path string - Only return results where the request path matches the given regular expresssion.
method string - Only return results where the request method matches the given regular expresssion.
status string - Filter results by HTTP status codes.
rangeStart string (required) - Only return results from after this timestamp, must be an RFC3339 timestamp string
rangeEnd string (required) - Only return results from before this timestamp, must be an RFC3339 timestamp string
pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/applications/42/access_logs/no_total \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "method": "POST",
      "requestPayload": "information in a payload sent with a request",
      "requestUri": "https://robelaltenwerth.net/",
      "responsePayload": "information in a payload sent with a response",
      "status": 94,
      "time": "2016-11-03T04:28:37Z",
      "uuid": "e98d2238b20b400a94efd0b7d51d97de"
    }
  ]
}

#Get all access logs

GET /v1/access_logs

Fetches the access logs for the entire account. Sensitive requests (logins) are always filtered from the logs.

Query Parameters

rangeStart string (required) - Only return results from after this timestamp, must be an RFC3339 timestamp string
rangeEnd string (required) - Only return results from before this timestamp, must be an RFC3339 timestamp string
path string - Only return results where the request path matches the given regular expresssion.
method string - Only return results where the request method matches the given regular expresssion.
status string - Filter results by HTTP status codes.
pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/access_logs \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "method": "POST",
      "requestPayload": "information in a payload sent with a request",
      "requestUri": "https://robelaltenwerth.net/",
      "responsePayload": "information in a payload sent with a response",
      "status": 94,
      "time": "2016-11-03T04:28:37Z",
      "uuid": "e98d2238b20b400a94efd0b7d51d97de"
    }
  ]
}

#List Webhook activation Log Entries

GET /v1/webhook_activation_logs

Webhook activation log entries would be created as soon as an integration request triggered an effect with a webhook

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
integrationRequestUuid string - Filter results by integration request UUID.
webhookId int - Filter results by Webhook.
applicationId int
campaignId int - Filter results by campaign.
createdBefore string - Only return events created before this date.
createdAfter string - Filter results where request and response times to return entries after parameter value, expected to be an RFC3339 timestamp string.

Request

curl https://example.talon.one/v1/webhook_activation_logs \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "applicationId": 92,
      "campaignId": 44,
      "created": "2016-08-24T17:58:42Z",
      "integrationRequestUuid": "5c87e02d58d14a0f981050df85c412b6",
      "webhookId": 97
    }
  ]
}

#List Webhook Log Entries

GET /v1/webhook_logs

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.
status string - Filter results by HTTP status codes.
webhookId int - Filter results by Webhook.
applicationId int
campaignId int - Filter results by campaign.
requestUuid string - Filter results by request UUID.
createdBefore string - Filter results where request and response times to return entries before parameter value, expected to be an RFC3339 timestamp string.
createdAfter string - Filter results where request and response times to return entries after parameter value, expected to be an RFC3339 timestamp string.

Request

curl https://example.talon.one/v1/webhook_logs \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "applicationId": 96,
      "id": "69",
      "integrationRequestUuid": "95ddfa36411c4f89a3dd4a51dd7eed7e",
      "request": "WebhookLogEntry.request",
      "requestTime": "2018-10-15T15:39:19.949628807Z",
      "response": "WebhookLogEntry.response",
      "responseTime": "2019-01-04T15:39:19.949628807Z",
      "status": 27,
      "url": "http://batz.org/kristy.glover",
      "webhookId": 17
    }
  ]
}

#Accounts & Users

Operations for updating account information such as billing email addresses, inviting users, etc.

#List Users in your account

GET /v1/users

Retrieve all users in your account.

Query Parameters

pageSize integer - The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
skip integer - Skips the given number of items when paging through large result sets.
sort string - The field by which results should be sorted. Sorting defaults to ascending order, prefix the field name with `-` to sort in descending order.

Request

curl https://example.talon.one/v1/users \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "accountId": 25,
      "created": "2016-09-05T06:51:11Z",
      "email": "elenora.breitenberg@waters.biz",
      "id": 64,
      "inviteToken": "stg43pmzi9",
      "lastActivity": "2016-06-19T00:25:59Z",
      "latestFeature": "User.latestFeature",
      "modified": "2016-11-15T23:21:57Z",
      "name": "Justina Terry",
      "policy": {
        "account_1": "admin",
        "shop_3": "read"
      },
      "releaseUpdate": true,
      "state": "invited"
    }
  ]
}

#Get a single User

GET /v1/users/{userId}

Retrieves the data (including an invitation code) for a user. Non-admin users can only get themselves.

Parameters

userId integer

Request

curl https://example.talon.one/v1/users/42 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "accountId": 25,
  "created": "2016-09-05T06:51:11Z",
  "email": "elenora.breitenberg@waters.biz",
  "id": 64,
  "inviteToken": "stg43pmzi9",
  "lastActivity": "2016-06-19T00:25:59Z",
  "latestFeature": "User.latestFeature",
  "modified": "2016-11-15T23:21:57Z",
  "name": "Justina Terry",
  "policy": {
    "account_1": "admin",
    "shop_3": "read"
  },
  "releaseUpdate": true,
  "state": "invited"
}

#Update User data

PUT /v1/users/{userId}

Parameters

userId integer

Request

curl https://example.talon.one/v1/users/42 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "email": "bernice_gleason@dooley.name",
  "latestFeature": "UpdateUser.latestFeature",
  "name": "Domenico Abbott",
  "newPassword": "j4684b0zes",
  "password": "ijexlctpf3",
  "policy": {
    "account_1": "admin",
    "shop_3": "read"
  },
  "releaseUpdate": true,
  "state": "active"
}'

Response (200)

{
  "accountId": 25,
  "created": "2016-09-05T06:51:11Z",
  "email": "elenora.breitenberg@waters.biz",
  "id": 64,
  "inviteToken": "stg43pmzi9",
  "lastActivity": "2016-06-19T00:25:59Z",
  "latestFeature": "User.latestFeature",
  "modified": "2016-11-15T23:21:57Z",
  "name": "Justina Terry",
  "policy": {
    "account_1": "admin",
    "shop_3": "read"
  },
  "releaseUpdate": true,
  "state": "invited"
}

#Delete a User

DELETE /v1/users/{userId}

Parameters

userId integer

Request

curl https://example.talon.one/v1/users/42 \
 -X DELETE \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (204)

{}

#Invite a new user to your account

POST /v1/invites

Creates a new invitation within your account. To trigger sending of an invitation email, use the createInviteEmail operation below.

Request

curl https://example.talon.one/v1/invites \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "acl": {
    "account_1": "admin",
    "shop_3": "read"
  },
  "email": "anastasia@hilpert.name",
  "name": "Ms. Arnoldo Schneider"
}'

Response (201)

{
  "accountId": 25,
  "created": "2016-09-05T06:51:11Z",
  "email": "elenora.breitenberg@waters.biz",
  "id": 64,
  "inviteToken": "stg43pmzi9",
  "lastActivity": "2016-06-19T00:25:59Z",
  "latestFeature": "User.latestFeature",
  "modified": "2016-11-15T23:21:57Z",
  "name": "Justina Terry",
  "policy": {
    "account_1": "admin",
    "shop_3": "read"
  },
  "releaseUpdate": true,
  "state": "invited"
}

#(Re)send an invitation email

POST /v1/invite_emails

Given a token & email address, send an invitation email.

Request

curl https://example.talon.one/v1/invite_emails \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "email": "gracie.emmerich@romagueratillman.com",
  "token": "u0jfeilsra"
}'

Response (201)

{
  "email": "gracie.emmerich@romagueratillman.com",
  "token": "u0jfeilsra"
}

#Accept an invitation

POST /v1/accept_invite

Consumes the supplied invitation code and creates a new user with the given email & password. The email provided here does not need to match the one used to create the invitation code. (That is, users can choose an alternate email address when accepting an invite).

Request

curl https://example.talon.one/v1/accept_invite \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "email": "bruce_goodwin@spencer.biz",
  "inviteToken": "shu73na28t",
  "name": "Jamarcus Breitenberg",
  "password": "319v990k9m"
}'

Response (201)

{
  "created": "2016-01-18T22:00:49Z",
  "token": "zb8buj39cd",
  "userId": 81
}

#Request a password reset

POST /v1/password_recovery_emails

Sends an email with a password recovery link to the email of an existing account.

Request

curl https://example.talon.one/v1/password_recovery_emails \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "email": "jordi@feest.com"
}'

Response (204)

{
  "email": "jordi@feest.com"
}

#Reset password

POST /v1/reset_password

Consumes the supplied password reset token and updates the password for the associated account.

Request

curl https://example.talon.one/v1/reset_password \
 -X POST \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "password": "tr81rabs0e",
  "resetToken": "2mffvsljug"
}'

Response (204)

{
  "password": "tr81rabs0e",
  "resetToken": "2mffvsljug"
}

#Get Account Details

GET /v1/accounts/{accountId}

Return the details of your companies Talon.One account.

Parameters

accountId integer

Request

curl https://example.talon.one/v1/accounts/42 \
 -H "authorization: Bearer $YOUR_TOKEN"

Response (200)

{
  "apiLimit": 32,
  "applicationCount": 18,
  "applicationLimit": 65,
  "billingEmail": "perry@hartmannmohr.org",
  "campaignLimit": 21,
  "campaignsActiveCount": 43,
  "campaignsInactiveCount": 96,
  "companyName": "Toy LLC",
  "created": "2016-10-23T07:46:26Z",
  "domainName": "Ernser,MillerandJaskolski.talon.one",
  "id": 25,
  "modified": "2016-03-14T13:14:09Z",
  "planExpires": "2016-01-06T12:08:43Z",
  "planName": "booked plan name",
  "state": "trial",
  "userCount": 1,
  "userLimit": 12
}

#Update Account

PUT /v1/accounts/{accountId}

Update the details of your companies Talon.One account. The fields below are the only ones that accept updates via the API.

Parameters

accountId integer

Request

curl https://example.talon.one/v1/accounts/42 \
 -X PUT \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -d '{
  "billingEmail": "ludie_hessel@koch.biz",
  "companyName": "Toy LLC"
}'

Response (200)

{
  "apiLimit": 32,
  "applicationCount": 18,
  "applicationLimit": 65,
  "billingEmail": "perry@hartmannmohr.org",
  "campaignLimit": 21,
  "campaignsActiveCount": 43,
  "campaignsInactiveCount": 96,
  "companyName": "Toy LLC",
  "created": "2016-10-23T07:46:26Z",
  "domainName": "Ernser,MillerandJaskolski.talon.one",
  "id": 25,
  "modified": "2016-03-14T13:14:09Z",
  "planExpires": "2016-01-06T12:08:43Z",
  "planName": "booked plan name",
  "state": "trial",
  "userCount": 1,
  "userLimit": 12
}