Skip to main content
Documentation Powered by Redocly

Integration API reference docs (1.0.0)

Download OpenAPI specification:Download

Use the Integration API to push data to and retrieve data from Talon.One in real time. For more background information about this API, see Integration API overview

For example, use this API to share shopping cart information as a session with Talon.One and evaluate promotion rules. You can also create custom events to track specific actions that do not fit into the session data model.

Ensure you authenticate to make requests to the API.

Are you looking for a different API? If you need the API to:

Authentication

api_key_v1

To authenticate in order to use the Integration API, generate an API key in the Campaign Manager then prefix it with ApiKey-v1.

To generate an API key:

  1. Log on to the Campaign Manager and open the Application of your choice, or create one.
  2. Click Settings > Developer settings.
  3. Click Create API Key and give it a title and an expiration date, then click Create API Key.

You can now use the API key in the HTTP header, prefixing it with ApiKey-v1:

Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3

Or use it inside an SDK, for example, with the JAVA SDK:

iApi.getApiClient().setApiKeyPrefix("ApiKey-v1");
iApi.getApiClient().setApiKey("dbc644d33aa74d582bd9479c59e16f970fe13bf3");
Security Scheme Type API Key
Header parameter name: Authorization

Audiences

Represents an arbitrary group of customer profiles grouped by mParticle.

Create audience

Create an audience. The audience can be created directly from scratch or can come from third party platforms.

To create an audience from an existing audience from a technology partner:

  1. Set the integration property to mparticle, segment etc., depending on a third-party platform.
  2. Set integrationId to the ID of this audience in a third-party platform.

To create an audience from an existing audience in another platform:

  1. Do not use the integration property.
  2. Set integrationId to the ID of this audience in the 3rd-party platform.

To create an audience from scratch:

  1. Only set the name property.

Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder.

Authorizations:
api_key_v1
    Request Body schema: application/json
    name
    required
    string non-empty

    The human-friendly display name for this audience.

    integration
    string

    The Talon.One-supported 3rd-party platform that this audience was created in.

    For example, mParticle, Segment, Selligent, Braze, or Iterable.

    Note: If you do not integrate with any of these platforms, do not use this property.

    integrationId
    string [ 1 .. 1000 ] characters

    The ID of this audience in the third-party integration.

    Note: To create an audience that doesn't come from a 3rd party platform, do not use this property.

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "Travel audience",
    • "integration": "mparticle",
    • "integrationId": "382370BKDB946"
    }

    Response samples

    Content type
    application/json
    {
    • "accountId": 3886,
    • "id": 6,
    • "created": "2020-06-10T09:05:27.993483Z",
    • "name": "Travel audience",
    • "integration": "mparticle",
    • "integrationId": "382370BKDB946"
    }

    Delete audience

    Delete an audience created by a third-party integration.

    Warning: This endpoint also removes any associations recorded between a customer profile and this audience.

    path Parameters
    audienceId
    required
    integer

    The ID of the audience. You get it via the id property when creating an audience.

    Responses

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "errors": [
      ],
    • "StatusCode": 0
    }

    Update audience

    Update an Audience created by a third-party integration.

    Authorizations:
    api_key_v1
      path Parameters
      audienceId
      required
      integer

      The ID of the audience. You get it via the id property when creating an audience.

      Request Body schema: application/json
      name
      required
      string non-empty

      The human-friendly display name for this audience.

      Responses

      Request samples

      Content type
      application/json
      {
      • "name": "mPTravel"
      }

      Response samples

      Content type
      application/json
      {
      • "accountId": 3886,
      • "id": 6,
      • "created": "2020-06-10T09:05:27.993483Z",
      • "name": "Travel audience",
      • "integration": "mparticle",
      • "integrationId": "382370BKDB946"
      }

      Delete audience memberships

      Remove all members from this audience.

      path Parameters
      audienceId
      required
      integer

      The ID of the audience. You get it via the id property when creating an audience.

      Responses

      Response samples

      Content type
      application/json
      {
      • "message": "string",
      • "errors": [
        ],
      • "StatusCode": 0
      }

      Update multiple customer profiles' audiences

      Update the specified customer profiles with the specified audiences. Use this endpoint when customers join or leave audiences.

      The limit of customer profiles per request is 1000.

      Authorizations:
      api_key_v1
        Request Body schema: application/json
        Array of objects <= 1000 [ items ]
        Array
        action
        required
        string
        Enum: "add" "delete"

        Defines the action to perform:

        • add: Adds the customer profile to the audience.
        • delete: Removes the customer profile from the audience.
        profileIntegrationId
        required
        string <= 1000 characters

        The ID of this customer profile in the third-party integration.

        audienceId
        required
        integer

        The ID of the audience. You get it via the id property when creating an audience.

        Responses

        Request samples

        Content type
        application/json
        {
        • "data": [
          ]
        }

        Response samples

        Content type
        application/json
        {
        • "message": "string",
        • "errors": [
          ],
        • "StatusCode": 0
        }

        Update profile attributes for all customers in audience

        Update the specified profile attributes to the provided values for all customers in the specified audience.

        Authorizations:
        api_key_v1
          path Parameters
          audienceId
          required
          integer

          The ID of the audience. You get it via the id property when creating an audience.

          Request Body schema: application/json
          property name*
          any

          Responses

          Request samples

          Content type
          application/json
          {
          • "my_attribute_1": "some value",
          • "my_attribute_2": "some other value",
          • "my_attribute_3": "some other value"
          }

          Response samples

          Content type
          application/json
          {
          • "message": "string",
          • "errors": [
            ],
          • "StatusCode": 0
          }

          Coupons

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

          Create coupon reservation

          Create a coupon reservation for specified customer profiles on the specified coupon.

          Reserving a coupon allows you to associate a coupon code to a given customer(s). You can then list the reserved coupons of a given customer with the List customer data endpoint.

          If a coupon gets created for a specific user, it will automatically show up in their coupons.

          When a user redeems a coupon, a reservation is automatically created after the redemption and the used coupon will be returned in the List customer data endpoint.

          Important:

          • This endpoint creates a soft reservation. Any customer can use a reserved coupon code and proceed to checkout.
          • To create a hard reservation, use the Create coupons or Create coupons for multiple recipients endpoints setting the recipientsIntegrationId property.

          For example, you can use this endpoint and List customer data to create a coupon wallet by reserving coupon codes for a customer, and then displaying their coupon wallet when they visit your store.

          Authorizations:
          api_key_v1
            path Parameters
            couponValue
            required
            string

            The code of the coupon.

            Request Body schema: application/json
            integrationIDs
            required
            Array of strings

            List of customer integration IDs.

            Responses

            Request samples

            Content type
            application/json
            {
            • "integrationIDs": [
              ]
            }

            Response samples

            Content type
            application/json
            {
            • "id": 6,
            • "created": "2020-06-10T09:05:27.993483Z",
            • "campaignId": 211,
            • "value": "XMAS-20-2021",
            • "usageLimit": 100,
            • "discountLimit": 30,
            • "startDate": "2019-08-24T14:15:22Z",
            • "expiryDate": "2019-08-24T14:15:22Z",
            • "limits": [
              ],
            • "usageCounter": 10,
            • "discountCounter": 0,
            • "discountRemainder": 0,
            • "attributes": { },
            • "referralId": 326632952,
            • "recipientIntegrationId": "URNGV8294NV",
            • "importId": 0,
            • "reservation": false,
            • "batchId": "32535-43255"
            }

            Delete coupon reservations

            Remove all the coupon reservations from the provided customer profile integration IDs and the provided coupon code.

            Authorizations:
            api_key_v1
              path Parameters
              couponValue
              required
              string

              The code of the coupon.

              Request Body schema: application/json
              integrationIDs
              required
              Array of strings

              List of customer integration IDs.

              Responses

              Request samples

              Content type
              application/json
              {
              • "integrationIDs": [
                ]
              }

              Response samples

              Content type
              application/json
              {
              • "message": "string",
              • "errors": [
                ],
              • "StatusCode": 0
              }

              List customers that have this coupon reserved

              Return all customers that have this coupon marked as reserved.

              Coupons are reserved in the following ways:

              Authorizations:
              api_key_v1
                path Parameters
                couponValue
                required
                string

                The code of the coupon.

                Responses

                Response samples

                Content type
                application/json
                {
                • "totalResultSize": 0,
                • "data": [
                  ]
                }

                Customer profiles

                Represents the customer's information. For instance, their contact information.

                Update multiple customer profiles

                Update (or create) up to 1000 customer profiles in 1 request.

                The integrationId must be any identifier that remains stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

                A customer profile can be linked to one or more sessions.

                Authorizations:
                api_key_v1
                  query Parameters
                  silent
                  string
                  Default: "yes"

                  Possible values: yes or no.

                  • yes: Increases the perfomance of the API call by returning a 204 response.
                  • no: Returns a 200 response that contains essential data such as the updated customer profiles and session-related information.
                  Request Body schema: application/json
                  Array of objects[ items ]
                  Array
                  integrationId
                  required
                  string <= 1000 characters

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

                  To get the integrationId of the profile from a sessionId, use the Update customer session.

                  object

                  Arbitrary properties associated with this item

                  Responses

                  Request samples

                  Content type
                  application/json
                  {
                  • "customerProfiles": [
                    ]
                  }

                  Response samples

                  Content type
                  application/json
                  {
                  • "integrationStates": [
                    ]
                  }

                  Update customer profile

                  Update (or create) a Customer Profile.

                  Performance tips

                  Updating a customer profile returns a response with the requested integration state.

                  You can use the responseContent property to save yourself extra API calls. For example, you can get the customer profile details directly without extra requests.

                  You can also set runRuleEngine to false to prevent unwanted rule executions. This allows you to improve response times.

                  If runRuleEngine is set to true, the response includes:

                  • The effects generated by the triggered campaigns.
                  • The created coupons and referral objects.
                  Authorizations:
                  api_key_v1
                    path Parameters
                    integrationId
                    required
                    string

                    The integration identifier for this customer profile. Must be:

                    • Unique within the deployment.
                    • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

                    Once set, you cannot update this identifier.

                    query Parameters
                    runRuleEngine
                    boolean
                    Default: false

                    Indicates whether to run the rule engine. Setting this property to false improves response times.

                    dry
                    boolean

                    Indicates whether to persist the changes. Changes are ignored when dry=true. Only used when runRuleEngine is set to true.

                    Request Body schema: application/json
                    object

                    Arbitrary properties associated with this item

                    object
                    responseContent
                    Array of strings
                    Items Enum: "customerProfile" "triggeredCampaigns" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons"

                    Optional list of extra data that you want to get in the response. Use this property to get as much data as you need in one request instead of sending extra requests to other endpoints.

                    Note: ruleFailureReasons is always part of the response when the Application type is sandbox.

                    Responses

                    Request samples

                    Content type
                    application/json
                    {
                    • "attributes": {
                      },
                    • "audiencesChanges": {
                      },
                    • "responseContent": [
                      ]
                    }

                    Response samples

                    Content type
                    application/json
                    {
                    • "customerSession": {
                      },
                    • "customerProfile": {
                      },
                    • "event": {
                      },
                    • "loyalty": {
                      },
                    • "referral": {
                      },
                    • "coupons": [
                      ],
                    • "triggeredCampaigns": [
                      ],
                    • "effects": [
                      ],
                    • "ruleFailureReasons": [
                      ],
                    • "createdCoupons": [
                      ],
                    • "createdReferrals": [
                      ],
                    • "awardedGiveaways": [
                      ],
                    • "return": {
                      },
                    • "previousReturns": [
                      ]
                    }

                    Delete customer's personal data

                    Delete all attributes on the customer profile and on entities that reference this customer profile.

                    Important: To preserve performance, we recommend avoiding deleting customer data during peak-traffic hours.

                    Authorizations:
                    api_key_v1
                      path Parameters
                      integrationId
                      required
                      string

                      The integration ID of the customer profile. You can get the integrationId of a profile using:

                      Responses

                      Response samples

                      Content type
                      application/json
                      {
                      • "message": "string",
                      • "errors": [
                        ],
                      • "StatusCode": 0
                      }

                      List customer data

                      Return the customer inventory regarding entities referencing this customer profile's integrationId.

                      Typical entities returned are: customer profile information, referral codes, loyalty points and reserved coupons. Reserved coupons also include redeemed coupons.

                      You can also use this endpoint to get the projected loyalty balances in order to notify your customers about points that are about to expire, or to remind them how many points they have.

                      Authorizations:
                      api_key_v1
                        path Parameters
                        integrationId
                        required
                        string

                        The integration ID of the customer profile. You can get the integrationId of a profile using:

                        query Parameters
                        profile
                        boolean

                        Set to true to include customer profile information in the response.

                        referrals
                        boolean

                        Set to true to include referral information in the response.

                        coupons
                        boolean

                        Set to true to include coupon information in the response.

                        loyalty
                        boolean

                        Set to true to include loyalty information in the response.

                        giveaways
                        boolean

                        Set to true to include giveaways information in the response.

                        loyaltyProjectionEndDate
                        string <date-time>

                        Set an end date to query the projected loyalty balances. You can project results up to 31 days from today.

                        Responses

                        Response samples

                        Content type
                        application/json
                        {
                        • "profile": {
                          },
                        • "loyalty": {
                          },
                        • "referrals": [
                          ],
                        • "coupons": [
                          ],
                        • "giveaways": [
                          ]
                        }

                        Customer sessions

                        Represents the data related to a customer session. Typically, a customer session is the value and content of the customer's cart.

                        Sessions can be anonymous or linked to a customer profile and they have a life cycle from open to closed. In general, a session is closed when the customer completes the checkout step.

                        Sessions are a key concept of Talon.One, we strongly recommend you read the documentation about customer sessions.

                        Get customer session

                        Get customer session data.

                        Authorizations:
                        api_key_v1
                          path Parameters
                          customerSessionId
                          required
                          string

                          The integration ID of the customer session. You set this ID when you create a customer session.

                          You can see existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint.

                          Responses

                          Response samples

                          Content type
                          application/json
                          {
                          • "customerSession": {
                            }
                          }

                          Update customer session

                          Update or create a customer session. For example, use this endpoint to share the content of a customer's cart with Talon.One and to check which promotion rules apply.

                          Note: The currency for the session and the cart items in the session is the same as the Application that owns this session.

                          Session management

                          The Talon.One platform supports multiple simultaneous sessions for the same profile. If you have multiple ways of accessing the same Application you can either:

                          • Track multiple independent sessions or,
                          • Use the same session across all of them.

                          You should share sessions when application access points share other state, such as the user's cart. If two points of access to the application have independent states, for example a user can have different items in their cart across the two) they should use independent customer session ID's.

                          See more information and tips about session management in the documentation.

                          Sessions and customer profiles

                          • To link a session to a customer profile, set the profileId parameter in the request body to a customer profile's integrationId.
                          • While you can create an anonymous session with profileId="", we recommend you use a guest ID instead.

                          Note: You do not have to create a customer profile first. If the specified profile does not exist, an empty profile is created automatically.

                          Performance tips

                          Updating a customer session returns a response with the requested integration state.

                          You can use the responseContent property to save yourself extra API calls. For example, you can get the customer profile details directly without extra requests.

                          For more information, see the integration tutorial.

                          Authorizations:
                          api_key_v1
                            path Parameters
                            customerSessionId
                            required
                            string

                            The integration ID of the customer session. You set this ID when you create a customer session.

                            You can see existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint.

                            query Parameters
                            dry
                            boolean

                            Indicates whether to persist the changes. Changes are ignored when dry=true.

                            Request Body schema: application/json
                            required
                            object
                            responseContent
                            Array of strings
                            Items Enum: "customerSession" "customerProfile" "coupons" "triggeredCampaigns" "referral" "loyalty" "event" … 3 more

                            Optional list of extra data that you want to get in the response. Use this property to get as much data as you need in one request instead of sending extra requests to other endpoints.

                            Note: ruleFailureReasons is always part of the response when the Application type is sandbox.

                            Responses

                            Request samples

                            Content type
                            application/json
                            {
                            • "customerSession": {
                              },
                            • "responseContent": [
                              ]
                            }

                            Response samples

                            Content type
                            application/json
                            {
                            • "customerSession": {
                              },
                            • "customerProfile": {
                              },
                            • "event": {
                              },
                            • "loyalty": {
                              },
                            • "referral": {
                              },
                            • "coupons": [
                              ],
                            • "triggeredCampaigns": [
                              ],
                            • "effects": [
                              ],
                            • "ruleFailureReasons": [
                              ],
                            • "createdCoupons": [
                              ],
                            • "createdReferrals": [
                              ],
                            • "awardedGiveaways": [
                              ],
                            • "return": {
                              },
                            • "previousReturns": [
                              ]
                            }

                            Return cart items

                            Create a new return request for the specified cart items.

                            This endpoint automatically changes the session state from closed to partially returned.

                            Its behavior depends on whether cart item flattening is enabled for the campaign.

                            Note: This will roll back any effects associated with these cart items. For more information, see our documentation on session states and this tutorial.

                            Authorizations:
                            api_key_v1
                              path Parameters
                              customerSessionId
                              required
                              string

                              The integration ID of the customer session. You set this ID when you create a customer session.

                              You can see existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint.

                              query Parameters
                              dry
                              boolean

                              Indicates whether to persist the changes. Changes are ignored when dry=true.

                              Request Body schema: application/json
                              required
                              object
                              responseContent
                              Array of strings
                              Items Enum: "customerSession" "customerProfile" "coupons" "triggeredCampaigns" "referral" "loyalty" "event" … 1 more

                              Optional list of extra data that you want to get in the response. Use this property to get as much data as you need in one request instead of sending extra requests to other endpoints.

                              Note: ruleFailureReasons is always part of the response when the Application type is sandbox..

                              Responses

                              Request samples

                              Content type
                              application/json
                              {
                              • "return": {
                                },
                              • "responseContent": [
                                ]
                              }

                              Response samples

                              Content type
                              application/json
                              {
                              • "customerSession": {
                                },
                              • "customerProfile": {
                                },
                              • "event": {
                                },
                              • "loyalty": {
                                },
                              • "referral": {
                                },
                              • "coupons": [
                                ],
                              • "triggeredCampaigns": [
                                ],
                              • "effects": [
                                ],
                              • "ruleFailureReasons": [
                                ],
                              • "createdCoupons": [
                                ],
                              • "createdReferrals": [
                                ],
                              • "awardedGiveaways": [
                                ],
                              • "return": {
                                },
                              • "previousReturns": [
                                ]
                              }

                              Events

                              Represents a single occurrence of various customer actions. There are 2 versions:

                              • For V1 events, each customer session contains one or more events. For example, updating a customer session records a talon_session_updated event.
                              • For V2 events, each customer profile contains one or more events. For example, updating a customer session records a talon_session_updated event linked to the profile in question.

                              Track event

                              Important: This endpoint is DEPRECATED. Use Track Event V2 instead.

                              Triggers a custom event in a customer session. You can then check this event in your rules. Important: Talon.One offers a set of built-in events, ensure you do not create a custom event when you can use a built-in event. For example, use this endpoint to trigger an event when a user updates their payment information.

                              Before using this endpoint, create your event as a custom attribute of type event. See the Developer docs.

                              An event is always part of a session. If either the profile or the session does not exist, a new empty profile/session is created. If the specified session already exists, it must belong to the same profileId or an error will be returned.

                              Authorizations:
                              api_key_v1
                                query Parameters
                                dry
                                boolean

                                Indicates whether to persist the changes. Changes are ignored when dry=true.

                                Request Body schema: application/json
                                type
                                required
                                string non-empty

                                A string representing the event. Must not be a reserved event name.

                                required
                                object

                                Arbitrary additional JSON data associated with the event.

                                sessionId
                                required
                                string non-empty

                                The ID of the session that this event occurred in.

                                profileId
                                string

                                ID of the customers profile as used within this Talon.One account.

                                Note: If the customer does not yet have a known profileId, we recommend you use a guest profileId.

                                Responses

                                Request samples

                                Content type
                                application/json
                                {
                                • "profileId": "URNGV8294NV",
                                • "type": "pageViews",
                                • "attributes": {
                                  },
                                • "sessionId": "175KJPS947296"
                                }

                                Response samples

                                Content type
                                application/json
                                {
                                • "session": {
                                  },
                                • "profile": {
                                  },
                                • "event": {
                                  },
                                • "loyalty": {
                                  },
                                • "coupon": {
                                  }
                                }

                                Track event V2

                                Triggers a custom event. You can then check this event in your rules.

                                Important: Talon.One offers a set of built-in events, ensure you do not create a custom event when you can use a built-in event.

                                For example, use this endpoint to trigger an event when a user updates their payment information.

                                Before using this endpoint, create your event as a custom attribute of type event. See the Developer docs.

                                Important: profileId is required. An event V2 is associated with a customer profile.

                                Authorizations:
                                api_key_v1
                                  query Parameters
                                  silent
                                  string
                                  Default: "yes"

                                  Possible values: yes or no.

                                  • yes: Increases the perfomance of the API call by returning a 204 response.
                                  • no: Returns a 200 response that contains essential data such as the updated customer profiles and session-related information.
                                  dry
                                  boolean

                                  Indicates whether to persist the changes. Changes are ignored when dry=true.

                                  Request Body schema: application/json
                                  type
                                  required
                                  string non-empty

                                  A string representing the event. Must not be a reserved event name.

                                  profileId
                                  string

                                  ID of the customers profile as used within this Talon.One account.

                                  Note: If the customer does not yet have a known profileId, we recommend you use a guest profileId.

                                  object

                                  Arbitrary additional JSON data associated with the event.

                                  responseContent
                                  Array of strings
                                  Items Enum: "customerProfile" "triggeredCampaigns" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons"

                                  Optional list of requested information to be present on the response related to the tracking custom event.

                                  Responses

                                  Request samples

                                  Content type
                                  application/json
                                  {
                                  • "profileId": "URNGV8294NV",
                                  • "type": "email_opened",
                                  • "attributes": {
                                    },
                                  • "responseContent": [
                                    ]
                                  }

                                  Response samples

                                  Content type
                                  application/json
                                  {
                                  • "customerSession": {
                                    },
                                  • "customerProfile": {
                                    },
                                  • "event": {
                                    },
                                  • "loyalty": {
                                    },
                                  • "referral": {
                                    },
                                  • "coupons": [
                                    ],
                                  • "triggeredCampaigns": [
                                    ],
                                  • "effects": [
                                    ],
                                  • "ruleFailureReasons": [
                                    ],
                                  • "createdCoupons": [
                                    ],
                                  • "createdReferrals": [
                                    ],
                                  • "awardedGiveaways": [
                                    ],
                                  • "return": {
                                    },
                                  • "previousReturns": [
                                    ]
                                  }

                                  Referrals

                                  A referral is a code shared between a customer and a prospect. A referral is defined by an advocate, a friend and a referral code. The advocate is the person who invited their friend via referral program. The friend is the person who receives the invite from an advocate. The referral code is a code which is generated similar to a coupon code the code can be redeemed by either one or multiple advocates.

                                  Create referral code for an advocate

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

                                  Authorizations:
                                  api_key_v1
                                    Request Body schema: application/json
                                    campaignId
                                    required
                                    integer

                                    ID of the campaign from which the referral received the referral code.

                                    advocateProfileIntegrationId
                                    required
                                    string <= 1000 characters

                                    The Integration ID of the Advocate's Profile.

                                    startDate
                                    string <date-time> >= 0

                                    Timestamp at which point the referral code becomes valid.

                                    expiryDate
                                    string <date-time> >= 0

                                    Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.

                                    usageLimit
                                    integer [ 0 .. 999999 ]

                                    The number of times a referral code can be used. 0 means no limit but any campaign usage limits will still apply.

                                    friendProfileIntegrationId
                                    string

                                    An optional Integration ID of the Friend's Profile

                                    object

                                    Arbitrary properties associated with this item.

                                    Responses

                                    Request samples

                                    Content type
                                    application/json
                                    {
                                    • "startDate": "2020-11-10T23:00:00Z",
                                    • "expiryDate": "2021-11-10T23:00:00Z",
                                    • "usageLimit": 1,
                                    • "campaignId": 78,
                                    • "advocateProfileIntegrationId": "URNGV8294NV",
                                    • "friendProfileIntegrationId": "BZGGC2454PA",
                                    • "attributes": { }
                                    }

                                    Response samples

                                    Content type
                                    application/json
                                    {
                                    • "id": 6,
                                    • "created": "2020-06-10T09:05:27.993483Z",
                                    • "startDate": "2020-11-10T23:00:00Z",
                                    • "expiryDate": "2021-11-10T23:00:00Z",
                                    • "usageLimit": 1,
                                    • "campaignId": 78,
                                    • "advocateProfileIntegrationId": "URNGV8294NV",
                                    • "friendProfileIntegrationId": "BZGGC2454PA",
                                    • "attributes": { },
                                    • "importId": 0,
                                    • "code": "27G47Y54VH9L",
                                    • "usageCounter": 1,
                                    • "batchId": "tqyrgahe"
                                    }

                                    Create referral codes for multiple advocates

                                    Creates unique referral codes for multiple advocates. The code will be valid for the referral campaign for which it is created, indicated in the campaignId parameter, and one referral code will be associated with one advocate using the profile specified in the advocateProfileIntegrationId parameter as the advocate's profile.

                                    Authorizations:
                                    api_key_v1
                                      query Parameters
                                      silent
                                      string
                                      Default: "yes"

                                      Possible values: yes or no.

                                      • yes: Increases the perfomance of the API call by returning a 204 response.
                                      • no: Returns a 200 response that contains essential data such as the updated customer profiles and session-related information.
                                      Request Body schema: application/json
                                      campaignId
                                      required
                                      integer

                                      The ID of the campaign from which the referral received the referral code.

                                      advocateProfileIntegrationIds
                                      required
                                      Array of strings [ 1 .. 1000 ] items

                                      An array containing all the respective advocate profiles.

                                      usageLimit
                                      required
                                      integer [ 0 .. 999999 ]

                                      The number of times a referral code can be used. 0 means no limit but any campaign usage limits will still apply.

                                      startDate
                                      string <date-time> >= 0

                                      Timestamp at which point the referral code becomes valid.

                                      expiryDate
                                      string <date-time> >= 0

                                      Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.

                                      object

                                      Arbitrary properties associated with this item.

                                      validCharacters
                                      Array of strings

                                      List of characters used to generate the random parts of a code. By default, the list of characters is equivalent to the [A-Z, 0-9] regular expression.

                                      referralPattern
                                      string [ 3 .. 100 ] characters

                                      The pattern used to generate referrals. The character # is a placeholder and is replaced by a random character from the validCharacters set.

                                      Responses

                                      Request samples

                                      Content type
                                      application/json
                                      {
                                      • "startDate": "2020-11-10T23:00:00Z",
                                      • "expiryDate": "2021-11-10T23:00:00Z",
                                      • "usageLimit": 1,
                                      • "campaignId": 45,
                                      • "advocateProfileIntegrationIds": [
                                        ],
                                      • "attributes": { },
                                      • "validCharacters": [
                                        ],
                                      • "referralPattern": "REF-###-###"
                                      }

                                      Response samples

                                      Content type
                                      application/json
                                      {
                                      • "totalResultSize": 0,
                                      • "data": [
                                        ]
                                      }