Search Offers

1 min

POST

https://api.sandbox.tripleup.dev/partner/card-accounts/{cardholder_id}/offers.search

Search for offers, optionally by category.

Providing a latitude and longitude for proximity_target is highly encouraged. Doing so allows Triple to deliver the most relevant Offers and Merchant Locations.

The default behavior of this endpoint is the null query, which fetches triple offers recommendations based on a Customer's geo-location, transaction history, and offer interactions.

However, a Customer can also search directly for offers with ad hoc text queries and/or by faceting on offer category. This action replaces the null query with search terms and/or one or more offer category facets. For example, a Customer may search for 'italian food' in plain text and select the 'FOOD' offer category facet.

Search results are paginated, using the page_size and page_offset parameters. For example, page_size=10 and page_offset=30 corresponds to the 4th page of 10 offers.

Note that Offer Display Rules are enforced against all search results.

Path Parameters

cardholder_idEntityIdrequired
Example
triple-abc-123
Description
The triple-defined ID for the entity.

Body Parameters

bodyobject
- apply_filterApplyFilter
  Description
  Applies a search filter. If more than one filter property is specified, the filter condition is expressed as an AND of the specified filter properties.
  - categoryTripleOfferCategory
    Description
    **triple Offer Category**
  - exclude_offer_idsEntityId[]
    Description
    The triple-defined ID for the entity.
  - include_offer_idsEntityId[]
    Description
    The triple-defined ID for the entity.
  - modeOfferMode
    Description
    The offer delivery mode
  - typeOfferType
    Description
    The type of offer - card-linked, affiliate, categorical, etc.
  - activation_requiredActivationRequired
    Description
    Include/Exclude offers that require activation
- crowding_parametersCrowdingParameters
  Description
  Crowding parameters control the maximum number of consecutive offers that may share the same characteristic. **Supported parameters include**: **- mode:** ONLINE or IN_PERSON **- category:** RETAIL, FOOD, etc. **- merchant:** 'ACME inc.', 'Big Multinational Brand', etc. **NOTE:** Crowding maximums may be exceeded depending on the availability of relevant replacement offers for any given query. Crowding maximums do not apply for a particular offer characteristic if a search query filter is applied to that characterstic. (e.g. Filtering on mode: ONLINE will return exclusively ONLINE results, even if a crowding parameter for mode is specified.)
  - categoryinteger
  - merchantinteger
  - modeinteger
- page_offsetinteger
  Description
  The beginning index for the current page of offers.
  Default
  0
- page_sizeinteger
  Description
  The number of offers returned for the current page of search results.
  Default
  25
- proximity_targetGeoTarget
  Description
  The Geo-coordinates for the end-user's location, given as `latitude` and `longitude` values or as approximate location parameters. If providing postal_code, country_code is required and must be set to US, as only US ZIP codes are currently supported. If providing `latitude` and `longitude`, both fields must be set. If no location is provided, the default postal code for the Card Account or Card Program is used.
  - country_codeCountryCode
    Example
    US
    Description
    2-letter ISO-3166 country code
  - latitudeLatitude
    Example
    40.440624
  - longitudeLongitude
    Example
    -79.995888
  - postal_codePostalCode
    Example
    15206
    Description
    ZIP Code™, ZIP+4, or postal code
  - radiusRadius
    Description
    The distance in meters from the provided location. Default value of `35000m` is adjusted according to population density of a location (ie. Rural locations will target a broader search radius than urban locations).
    Default
    35000
- text_querystring
  Example
  italian food
  Description
  Text query used to search offers.

Responses

200Offers

object
- offersCardholderOfferPreview[]required
  - CardholderOfferCore
    - activation_requiredOfferActivationIsRequiredrequired
      Description
      Indicates whether or not a cardholder must activate this offer prior to transacting and qualifying for the offer reward. If true, transactions that occur prior to the date of the cardholder activating the offer will not qualify for the offer's reward.
    - external_idOfferExternalIdrequired
      Description
      Partner-provided, external ID for an Offer. External IDs should be **stable** and **never sensitive**. External IDs do not need to be globally unique, but we encourage the use of UUIDs. They must be unique for the Offer within the scope of its parent Content Provider. To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).
      - ExternalId
    - categoryTripleOfferCategoryrequired
      Description
      **triple Offer Category**
    - currency_codeCurrencyCoderequired
      Example
      USD
      Description
      3-character ISO-4217 currency code. Only USD is currently supported. Contact your Triple representative for support with additional currencies. Note that some values are not supported, particularly test and fund codes.
      Default
      USD
    - effective_dateOfferEffectiveDaterequired
      Example
      2021-12-01
      Description
      The first date on which the offer is valid.
    - expiration_dateOfferExpirationDate
      Example
      2021-12-31
      Description
      If specified, the last date on which the offer is valid.
    - headlineOfferHeadlinerequired
      Description
      The headline or title for the offer, appropriate for top-level display.
    - idEntityIdrequired
      Example
      triple-abc-123
      Description
      The triple-defined ID for the entity.
    - is_activatedOfferIsActivatedrequired
      Description
      **True** if an offer requires activation and has a valid activation. - Offers that are 'always on' (no activation required) are set to **False**. - Offers with an expired activation are set to **False**. - Offers that have never been activated are set to **False**.
    - activated_atOfferActivatedAt
      Example
      2022-07-15T15:56:36+0000
      Description
      If specified, the absolute time in ISO format for when the offer was activated or re-activated.
    - activation_expires_atOfferActivationExpiresAt
      Example
      2022-07-22T15:56:36+0000
      Description
      If specified, the absolute time in ISO format for when the offer activation expires.
    - merchant_logo_urlMerchantLogoUrl
      Description
      A link to the merchant's logo
    - merchant_nameMerchantAssumedNamerequired
      Description
      The (doing-business-as) name of the Merchant.
    - merchant_websiteMerchantWebsite
    - minimum_spendOfferMinimumSpend
      Description
      The minimum monetary value that a cardholder must spend for a transaction to qualify for this offer.
    - offer_modeOfferModerequired
      Description
      The offer delivery mode
    - offer_preferenceOfferPreferencerequired
    - reward_rateOfferRewardRate
      Description
      The reward percentage if this offer has a reward_type of percentage, the amount will be between 0.0 and 100.0
    - reward_typeOfferRewardTyperequired
      Description
      Indicates whether this offer is for a fixed or percentage-based amount.
    - reward_valueOfferRewardValue
      Description
      The fixed reward value if this offer has a reward_type of fixed, the amount must be greater than or equal to 0.
    - typeOfferTyperequired
      Description
      The type of offer - card-linked, affiliate, categorical, etc.
  - object
    - nearest_locationCardholderOfferLocation
      Description
      A location is **IN_PERSON_AND_ONLINE** or **IN_PERSON**. **IN_PERSON_AND_ONLINE** locations have a physical address and a url. **IN_PERSON**. locations have a physical address but no url. No locations are available for **ONLINE** offers.
      - addressStrictAddressrequired
        Description
        A physical address in the world, with required fields. triple uses address validation services to update and standardize addresses on our platform. Address data sent to the API may be updated as we process, validate, and normalize addresses.
        Address
        citystring
        Example
        PITTSBURGH
        Description
        Municipality or city name
        completeCompleteAddress
        Example
        7370 BAKER ST, STE 100 PITTSBURGH, PA 15206
        Description
        The complete delivery address, composed from the Address properties.
        country_codeCountryCode
        Example
        US
        Description
        2-letter ISO-3166 country code
        country_subdivision_codestring
        Example
        PA
        Description
        ISO-3166-2; 2-6 letter code for a country subdivision
        latitudeLatitude
        Example
        40.440624
        longitudeLongitude
        Example
        -79.995888
        postal_codePostalCode
        Example
        15206
        Description
        ZIP Code™, ZIP+4, or postal code
        street_addressstring
        Example
        7370 BAKER ST, STE 100
        Description
        Single or multi-line physical address
      - distancenumber
        Description
        Distance, in kilometers, from the caller's location
      - emailstring
        Description
        An email address for the location.
      - idEntityIdrequired
        Example
        triple-abc-123
        Description
        The triple-defined ID for the entity.
      - is_in_radiusbooleanrequired
        Description
        The Offer MerchantLocation is within the Cardholder's search radius
      - location_namestring
        Example
        Peter Piper's Pizza - South Evermore
        Description
        The store location's name
      - phone_numberstring
        Description
        A phone number for the location.
      - urlstring<url>
- totalOfferSearchResultsTotalrequired
  Description
  The total number of offers available for the given query.

400TripleBadRequestError

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    The request is malformed.
  - exceptionstring<TripleBadRequestError>required
    Description
    The exception type.

403TripleNotAuthenticatedError

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    Client authentication failed.
  - exceptionstring<TripleNotAuthenticatedError>required
    Description
    The exception type.

404TripleInvalidPathError

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    The url path or path parameter is invalid.
  - exceptionstring<TripleInvalidPathError>required
    Description
    The exception type.

409TripleIntegrityError

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    The request was well-formed but violated entity integrity constraints.
  - exceptionstring<TripleIntegrityError>required
    Description
    The exception type.

415TripleUnsupportedMediaType

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    The request defined an unsupported media type.
  - exceptionstring<TripleUnsupportedMediaType>required
    Description
    The exception type.

422TripleUnprocessableEntity

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    The request was well-formed but could not be processed.
  - exceptionstring<TripleUnprocessableEntity>required
    Description
    The exception type.

500TripleInternalServerError

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    Triple was unable to process the request due to an internal error.
  - exceptionstring<TripleInternalServerError>required
    Description
    The exception type.

501TripleNotImplementedError

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    The request failed because it requires a feature that is not yet implemented.
  - exceptionstring<TripleNotImplementedError>required
    Description
    The exception type.

503TripleServiceUnavailable

object
- status_codeintegerrequired
  Description
  The 3-digit HTTP Response Status code
- contentobjectrequired
  Description
  The error response content.
  - detailsErrorResponseDetails
    Description
    An array of error detail
  - error_messagestringrequired
    Description
    Short description of what went wrong.
    Default
    The request failed due to a triple service interruption.
  - exceptionstring<TripleServiceUnavailable>required
    Description
    The exception type.

curl

curl --request POST \
     --url https://api.sandbox.tripleup.dev/partner/card-accounts/{cardholder_id}/offers.search \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "page_size": 25,
     "proximity_target": {
     "radius": 35000
     }
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "page_size": 25,
   "proximity_target": {
      "radius": 35000
   }
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.sandbox.tripleup.dev/partner/card-accounts/{cardholder_id}/offers.search", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.sandbox.tripleup.dev/partner/card-accounts/{cardholder_id}/offers.search")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "page_size": 25,
   "proximity_target": {
      "radius": 35000
   }
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.sandbox.tripleup.dev/partner/card-accounts/{cardholder_id}/offers.search"

payload = json.dumps({
   "page_size": 25,
   "proximity_target": {
      "radius": 35000
   }
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// Offers
{
  "offers": {},
  "total": 0
}

400

// TripleBadRequestError
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

403

// TripleNotAuthenticatedError
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

404

// TripleInvalidPathError
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

409

// TripleIntegrityError
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

415

// TripleUnsupportedMediaType
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

422

// TripleUnprocessableEntity
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

500

// TripleInternalServerError
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

501

// TripleNotImplementedError
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

503

// TripleServiceUnavailable
{
  "status_code": 0,
  "content": {
    "details": [
      ""
    ],
    "error_message": "",
    "exception": ""
  }
}

Search for offers, optionally by category.

Providing a latitude and longitude for is highly encouraged. Doing so allows Triple to deliver the most relevant Offers and Merchant Locations.

The default behavior of this endpoint is the null query, which fetches triple offers recommendations based on a Customer's geo-location, transaction history, and offer interactions.

Search results are paginated, using the page_size and page_offset parameters. For example, page_size=10 and page_offset=30 corresponds to the 4th page of 10 offers.

Note that Offer Display Rules are enforced against all search results.