triple API (v1.20.73)

Download OpenAPI specification:Download

Overview

The triple API enables Partners to integrate with the triple platform and Customers (consumers or card holders) to access offer content.

Connecting to our environment requires proper credentials. See the Authentication section for more details.

Additionally, triple content will be placed on a client-specific S3 bucket for ingestion. Please contact your triple client engagement manager for more information and to setup access.

Conventions

For a PATCH operation, any field marked required should always be passed and any other fields are optional and will not be updated if no field value is passed.

Concepts

Partner Types

Portfolio Managers are, generally, companies that provide services to multiple separate financial institutions such as regional banks, credit unions, or companies running open-enrollment rewards programs. These partners manage a portfolio of Publishers.

Publishers are, generally, banks or companies that offer one or more payment Card Programs to individuals.

Content Providers are the companies that publish Offers on the triple platform.

Card Programs

Card Programs represent a logical grouping of issued payment cards. A Publisher will create a Card Program for each debit or credit card offering, such as miles or cash back. For Publishers that are not Banks/Card Issuers (for example, a third-party rewards program), Card Programs can provide a simple way to organize Card Accounts.

Card Accounts represent the account connected to a payment card. Multiple physical cards may be associated with a single Card Account, such as when there are multiple authorized users or cards are replaced as lost, stolen, or expired. Each Transaction reported to triple must specify the Card Account to which it belongs.

Consumers represent individual card holders. A Consumer may be associated with multiple Card Accounts across a Publisher's Card Programs, such as when an individual has both a "miles" and a "cash back" card with the same bank. Multiple Consumers may be associated with the same Card Account, such as when there are multiple authorized users.

External IDs

triple requires Partners to specify IDs for the entities they create through the triple API. Generally, these "external" IDs only need to be unique within the scope of an object's parent entity, but we encourage the use of UUIDs to avoid confusion. External IDs must be stable and never sensitive, as they cannot be updated through the API.

triple will also create a unique ID for each entity created through the API.

Partner API

Most integration effort will focus on calls to endpoints under the /partner path. These endpoints will allow Content Providers to create and update Offer content and Publishers to register card holders, retrieve Offer content for display, and submit Transactions for Rewards.

The exposed APIs allow developers to authenticate to the triple service, register and unregister (delete) cards, retrieve affiliate offer URLs, submit transactions, and see user notifications delivered over webhooks.

Card Accounts

Operations related to managing Card Accounts.

A Card Account represents the account for which payment cards (credit or debit cards) are issued. A Transaction will belong to a single Card Account.

If a card is replaced or reissued (because it was lost or stolen), the Card Account itself should not change.

Card Accounts may have a status of "unenrolled" or "enrolled" for Rewards. A Card Account may only receive a Reward if it has a status of "enrolled" on the day of the eligible Transaction.

Get Card Account External

Returns a CardAccount instance using one or more of its associated external IDs:

  • external card account ID
  • external card program ID
  • external publisher ID

The receiver returns the same object as calling the /card-accounts/{id} endpoint with the triple card account ID if a matching CardAccount exists.

Authorizations:
triple_auth
Request Body schema: application/json
card_account_external_id
required
string (Card Account External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Account.

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 Card Account within the scope of its parent Card Program.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

card_program_external_id
string (Card Program External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Program.

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 Card Program within the scope of its parent Publisher.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

publisher_external_id
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

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 Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

Responses

Request samples

Content type
application/json
{
  • "card_account_external_id": "string",
  • "card_program_external_id": "string",
  • "publisher_external_id": "string"
}

Response samples

Content type
application/json
{
  • "card_program_id": "triple-abc-123",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "status": "ENROLLED",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

List Card Accounts

Returns a list of Card Accounts, optionally filtered.

Currently, this endpoint has a hard limit of returning up to 1,000 results. Future API releases may support paging results.

Authorizations:
triple_auth
query Parameters
publisher_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID of a Publisher. This parameter is ignored unless the client is a Portfolio Manager.

card_program_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

card_account_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

Responses

Response samples

Content type
application/json
{
  • "card_accounts": [
    ],
  • "total": 0
}

Create a Card Account

Creates a card account.

default_country_code may be set to the country associated with the card account. It defaults to US if it is not specified.

default_postal_code may be set to a postal code associated with the card account (e.g. domicile, other). The actual value is left to the discretion of the caller.

NB: The default_postal_code will be used in lieu of proximity_target if one is not specified during a CardAccount instance request for associated offers. If default_postal_code is not set for the card account, the CardProgram default_postal_code for the program will be used instead.

Authorizations:
triple_auth
Request Body schema: application/json
card_program_external_id
required
string (Card Program External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Program.

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 Card Program within the scope of its parent Publisher.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

default_country_code
string (CountryCode) = 2 characters ^[A-Z]{2}$

2-letter ISO-3166 country code

default_postal_code
string (PostalCode) [ 1 .. 15 ] characters

ZIP Code™, ZIP+4, or postal code

external_id
required
string (Card Account External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Account.

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 Card Account within the scope of its parent Card Program.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

publisher_external_id
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

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 Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

status
string (CardAccountEnrollmentStatus)
Default: "ENROLLED"
Enum: "ENROLLED" "NOT_ENROLLED" "CLOSED"
  • ENROLLED - The account is enrolled for rewards
  • NOT_ENROLLED - The account is not enrolled for rewards
  • CLOSED - The account is closed and cannot receive rewards

Responses

Request samples

Content type
application/json
{
  • "card_program_external_id": "string",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "publisher_external_id": "string",
  • "status": "ENROLLED"
}

Response samples

Content type
application/json
{
  • "card_program_id": "triple-abc-123",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "status": "ENROLLED",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Upsert Card Accounts in Bulk (Beta)

This endpoint provides significant performance advantages, over POSTing and PATCHing single Card Accounts, when creating or updating large numbers of Card Accounts. The behavior of this endpoint is similar to that of those endpoints except for some minor differences in how errors are handled.

Card Accounts that are not found, as resolved by their external_id and card_program_external_id (and publisher_external_id when applicable), are created. Existing objects are updated as though they were PATCHed.

You should check the result_type of the response to handle errors for individual items. If the top-level request returns a Client Error response (response codes 400-499), no Card Accounts from the batch were created or updated.

This endpoint is currently rate limited at 50 requests per minute.

Authorizations:
triple_auth
Request Body schema: application/json
action
required
string
Value: "upsert"

The action to take

required
Array of objects (CardAccountPost) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "action": "upsert",
  • "card_accounts": [
    ]
}

Response samples

Content type
application/json
{
  • "failures": [
    ],
  • "result_summary": { },
  • "result_type": "COMPLETE_FAILURE"
}

Get a Card Account

Get Card Account details.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "card_program_id": "triple-abc-123",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "status": "ENROLLED",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Card Account

(Alpha - this endpoint is subject to breaking change)

Enroll, un-enroll, or close a Card Account.

Card Accounts must be enrolled at the time of a transaction and not closed at the time of distribution in order to receive Rewards.

The date of enrollment defaults to the current date at UTC-12. The date of un-enrollment defaults to the current date at UTC+12. (This is to accommodate the possibility of a customer's current local date being different than the server's.)

A future API release will address the edge case of unenrolling and then re-enrolling an account within the same day.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
default_country_code
string (CountryCode) = 2 characters ^[A-Z]{2}$

2-letter ISO-3166 country code

default_postal_code
string (PostalCode) [ 1 .. 15 ] characters

ZIP Code™, ZIP+4, or postal code

status
string (CardAccountEnrollmentStatusPatch)
Enum: "ENROLLED" "NOT_ENROLLED" "CLOSED"
  • ENROLLED - The account is enrolled for rewards
  • NOT_ENROLLED - The account is not enrolled for rewards
  • CLOSED - The account is closed and cannot receive rewards

Responses

Request samples

Content type
application/merge-patch+json
{
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "status": "ENROLLED"
}

Response samples

Content type
application/json
{
  • "card_program_id": "triple-abc-123",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "status": "ENROLLED",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Card Programs

A Card Program is logical grouping of Card Accounts. Typically, this is a specific type of card offering by a Publisher - a debit or credit card with its own rewards, such as miles or cash back.

Alternatively, for Publishers that are not Banks or Card Issuers (for example, a third-party rewards program), this is simply a way to organize Card Accounts.

Card Accounts may not move between Card Programs and should not be represented in more than one Card Program.

List Card Programs

Returns a list of Card Programs, optionally filtered. This list can be used to find Card Programs' ID given an external ID.

Authorizations:
triple_auth
query Parameters
publisher_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID of a Publisher. This parameter is ignored unless the client is a Portfolio Manager.

card_program_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

Responses

Response samples

Content type
application/json
{
  • "card_programs": [
    ],
  • "total": 0
}

Create a Card Program

Creates a card program.

default_country_code may be set to the country associated with the card program. It defaults to US if it is not specified.

default_postal_code must be set to a postal code associated with the card program (e.g. domicile, other). The actual value is left to the discretion of the caller.

NB: The default_postal_code will be used in lieu of proximity_target if one is not specified during a CardAccount instance request for associated offers. If default_postal_code is not set for the card account, the CardProgram default_postal_code for the program will be used instead.

Authorizations:
triple_auth
Request Body schema: application/json
card_bins
Array of strings (CardProgramCardBins) <= 100 items [^\d{6}$]

The Bank Identification Numbers for cards in this Card Program.

Providing these values helps triple validate Transactions during reward processing and enforce card requirements during purchases through Affiliate Offers.

default_country_code
string (USDefaultedCountryCode) = 2 characters ^[A-Z]{2}$
Default: "US"

2-letter ISO-3166 country code

default_postal_code
required
string (PostalCode) [ 1 .. 15 ] characters

ZIP Code™, ZIP+4, or postal code

external_id
required
string (Card Program External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Card Program.

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 Card Program within the scope of its parent Publisher.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

name
required
string (CardProgramName) [ 1 .. 100 ] characters ^(?!\s)[\.]+(?<!\s)$

Display name of the Card Program

description
string (CardProgramDescription) <= 2000 characters

Description of the Card Program

hosted_ui_subdomain
string (HostedUiSubdomain) <= 60 characters

The subdomain for Triple hosted user interfaces.

program_currency
required
string (CurrencyCode) = 3 characters ^[A-Z]{3}$
Default: "USD"

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.

loyalty_unit
string (CardProgramLoyaltyUnit)
Enum: "POINTS" "MILES"

The unit used to pay with loyalty. Currently only POINTS and MILES are supported.

loyalty_conversion_rate
number <double> (CardProgramLoyaltyConversionRate) > 0

The rate of loyalty units earned per reward dollar earned.

For example, setting this to 100 would earn customers 100 loyalty miles for every reward dollar earned.

publisher_external_id
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

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 Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

Responses

Request samples

Content type
application/json
{
  • "card_bins": [
    ],
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "external_id": "string",
  • "name": "string",
  • "description": "string",
  • "hosted_ui_subdomain": "mybanque",
  • "program_currency": "USD",
  • "loyalty_unit": "POINTS",
  • "loyalty_conversion_rate": 100,
  • "publisher_external_id": "string"
}

Response samples

Content type
application/json
{
  • "card_bins": [
    ],
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "description": "string",
  • "external_id": "string",
  • "hosted_ui_subdomain": "mybanque",
  • "id": "triple-abc-123",
  • "loyalty_unit": "POINTS",
  • "loyalty_conversion_rate": 100,
  • "name": "string",
  • "program_currency": "USD",
  • "publisher_id": "triple-abc-123",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a Card Program

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "card_bins": [
    ],
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "description": "string",
  • "external_id": "string",
  • "hosted_ui_subdomain": "mybanque",
  • "id": "triple-abc-123",
  • "loyalty_unit": "POINTS",
  • "loyalty_conversion_rate": 100,
  • "name": "string",
  • "program_currency": "USD",
  • "publisher_id": "triple-abc-123",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Card Program

Updates a Card Program.

Only fields "name", and "card_bins" may be updated for a Card Program.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
name
string (CardProgramName) [ 1 .. 100 ] characters ^(?!\s)[\.]+(?<!\s)$

Display name of the Card Program

card_bins
Array of strings (CardProgramCardBins) <= 100 items [^\d{6}$]

The Bank Identification Numbers for cards in this Card Program.

Providing these values helps triple validate Transactions during reward processing and enforce card requirements during purchases through Affiliate Offers.

description
string (CardProgramDescription) <= 2000 characters

Description of the Card Program

hosted_ui_subdomain
string (HostedUiSubdomain) <= 60 characters

The subdomain for Triple hosted user interfaces.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "card_bins": [
    ],
  • "description": "string",
  • "hosted_ui_subdomain": "mybanque"
}

Response samples

Content type
application/json
{
  • "card_bins": [
    ],
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "default_country_code": "US",
  • "default_postal_code": "15206",
  • "description": "string",
  • "external_id": "string",
  • "hosted_ui_subdomain": "mybanque",
  • "id": "triple-abc-123",
  • "loyalty_unit": "POINTS",
  • "loyalty_conversion_rate": 100,
  • "name": "string",
  • "program_currency": "USD",
  • "publisher_id": "triple-abc-123",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Offer Activation

Operations related to Activating Offers for a Customer.

Some Offers are not eligible for Rewards until a Customer activates the Offer. Some Offers may require re-activation after a specified number of days.

Activate Offer By Id

Activate an offer by id for a specified card account

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

offer_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Offer Display

Operations related to displaying Offers to Customers.

Offer Display will generally follow the following flow:

  1. The Customer opens their mobile app or web page. A list of Recommended Offers are displayed to the Customer.
  2. The Customer may search Offers.
  3. As Offers are displayed, "Offer Viewed" Events are reported to triple.
  4. The Customer may tap or click to Activate an Offer, if required.
  5. The Customer may tap or click a thumbnail to View Offer Details.

Affiliate Offers are online Offers that require redirecting the Customer to a custom URL. The URL is specific to that Customer and is generated by calling the "Clicks" endpoint, usually while viewing the Offer Details.

Offer Display Rules can be configured to automatically exclude offers from the result sets.

Get Activated Offers

Lists activated offers for the card account designated in the url path.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/json
expires_within
integer or null
Enum: 1 3 5 10
include_expired
boolean
Default: false
page_offset
integer [ 0 .. 975 ]
Default: 0

The beginning index for the current page of activated offers.

page_size
integer [ 1 .. 100 ]
Default: 25

The number of offers returned for the current page of activated offers.

object (GeoTarget)

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.

Responses

Request samples

Content type
application/json
{
  • "expires_within": 1,
  • "include_expired": false,
  • "page_offset": 0,
  • "page_size": 25,
  • "proximity_target": {
    }
}

Response samples

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

Get Offer Categories

Get a list of categories with the count of active offers for each offer category that is available to a cardholder.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

query Parameters
exclude_inactive_offers
boolean
Deprecated

Include only categories with active offers

Responses

Response samples

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

Get Offer Recommendations

Get Offer Recommendations.

Get Offer Recommendations, optionally filtering by offer modes and/or offer categories. If include_modes and include_categories are omitted, specified as null or specified as an empty list, the application will default to include all values in the enum.

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

Note that Offer Display Exclusion Rules are enforced against all recommendations.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/json
object (ApplyFilter)

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.

include_categories
Array of strings (TripleOfferCategory) [ 1 .. 13 ] items
Default: ["AUTOMOTIVE","CHILDREN_AND_FAMILY","ELECTRONICS","ENTERTAINMENT","FINANCIAL_SERVICES","FOOD","HEALTH_AND_BEAUTY","HOME","OFFICE_AND_BUSINESS","RETAIL","SERVICES_AND_SUBSCRIPTIONS","TRAVEL","UTILITIES_AND_TELECOM"]
Items Enum: "AUTOMOTIVE" "CHILDREN_AND_FAMILY" "ELECTRONICS" "ENTERTAINMENT" "FINANCIAL_SERVICES" "FOOD" "HEALTH_AND_BEAUTY" "HOME" "OFFICE_AND_BUSINESS" "RETAIL" "SERVICES_AND_SUBSCRIPTIONS" "TRAVEL" "UTILITIES_AND_TELECOM"
include_modes
Array of strings (OfferMode) [ 1 .. 3 ] items
Default: ["ONLINE","IN_PERSON"]
Items Enum: "ONLINE" "IN_PERSON"
object (GeoTarget)

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.

page_size
integer [ 0 .. 1000 ]
Default: 100

Responses

Request samples

Content type
application/json
{
  • "apply_filter": {
    },
  • "include_categories": [
    ],
  • "include_modes": [
    ],
  • "proximity_target": {
    },
  • "page_size": 100
}

Response samples

Content type
application/json
{
  • "recommended_offers": [
    ],
  • "total": 10000
}

Search Offers

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.

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/json
object (ApplyFilter)

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.

object (CrowdingParameters)

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.)

page_offset
integer [ 0 .. 975 ]
Default: 0

The beginning index for the current page of offers.

page_size
integer [ 1 .. 100 ]
Default: 25

The number of offers returned for the current page of search results.

object (GeoTarget)

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.

text_query
string [ 0 .. 75 ] characters

Text query used to search offers. Text queries over 75 characters will be truncated.

Responses

Request samples

Content type
application/json
{
  • "apply_filter": {
    },
  • "crowding_parameters": {
    },
  • "page_offset": 0,
  • "page_size": 25,
  • "proximity_target": {
    },
  • "text_query": "italian food"
}

Response samples

Content type
application/json
{
  • "offers": [
    ],
  • "total": 10000
}

Get Offer Details by Cardholder

Get details and merchant locations for an offer associated with a card account.

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

Authorizations:
triple_auth
path Parameters
cardholder_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/json
offer_id
required
string (EntityId) [ 1 .. 100 ] characters

The triple-defined ID for the entity.

object (GeoTarget)

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.

Responses

Request samples

Content type
application/json
{
  • "offer_id": "triple-abc-123",
  • "proximity_target": {
    }
}

Response samples

Content type
application/json
{
  • "merchant_locations": [
    ],
  • "offer": {
    }
}

Get Offer Details

Get details and merchant locations for an offer.

Authorizations:
triple_auth
path Parameters
offer_id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "merchant_locations": [
    ],
  • "offer": {
    }
}

Offer Filters

Alpha - These endpoints are subject to breaking changes!

Exclude Offers from cardholders based on specific Offer properties. Filters apply globally, to all Publishers (if created by a Portfolio Manager) and Card Programs created by the caller. Any Offer matching the filter is immediately excluded from Search results, Recommendations, and Transaction Matching.

Merchants Search

Return a list of Merchants.

Authorizations:
triple_auth
query Parameters
page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 100

The size of pages for returned Objects.

query
string

Query string for merchant names.

Responses

Response samples

Content type
application/json
{
  • "merchants": [
    ],
  • "total": 12
}

Get Filter

Gets an Offer Filter.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    },
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update Filter

Updates an Offer Filter.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
description
string (OfferFilterDescription) [ 5 .. 500 ] characters

Readable description for this rule.

is_activated
boolean

If true, the filter is applied to offers.

name
string (OfferFilterName) [ 5 .. 50 ] characters

The short name for a filter.

object (OfferFilterOfferCondition)

Summary: Specifies the condition an offer must satisfy for a filter to apply. You may wish to exclude specific merchants or offers by specifying their IDs in the provided fields. Providing one or more category values will exclude all offers from those categories. Triple will not match new transactions against Offers meeting any of these conditions, even if the Offer was previously displayed to the cardholder.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    },
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Delete Filter

Deletes an Offer Filter.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "content": {
    }
}

List Filters

Lists all Offer Filters owned by the caller.

Authorizations:
triple_auth

Responses

Response samples

Content type
application/json
{
  • "filters": [
    ],
  • "total": 0
}

Create Filter

Creates a new Offer Filter.

Authorizations:
triple_auth
Request Body schema: application/json
description
required
string (OfferFilterDescription) [ 5 .. 500 ] characters

Readable description for this rule.

is_activated
boolean (OfferFilterIsActivated)
Default: true

If true, the filter is applied to offers.

name
required
string (OfferFilterName) [ 5 .. 50 ] characters

The short name for a filter.

required
object (OfferFilterOfferCondition)

Summary: Specifies the condition an offer must satisfy for a filter to apply. You may wish to exclude specific merchants or offers by specifying their IDs in the provided fields. Providing one or more category values will exclude all offers from those categories. Triple will not match new transactions against Offers meeting any of these conditions, even if the Offer was previously displayed to the cardholder.

Responses

Request samples

Content type
application/json
{
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "description": "Exclude all offers in the food or travel categories.\n",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "name": "Exclude food & travel",
  • "offer_condition": {
    },
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Offer Providers

Operations related to creating and updating Offers and Merchants.

List Card Exclusions

Returns a list of the Content Provider-defined Card Exclusions.

Transactions from payment cards with these identifiers will be excluded from matching the Offers you create.

Authorizations:
triple_auth
query Parameters
page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 100

The size of pages for returned Objects.

Responses

Response samples

Content type
application/json
{
  • "card_accounts": [
    ],
  • "total": 0
}

Update Card Exclusions

Update the list of Content Provider-defined Card Exclusions.

  • upsert to add card identifiers to the list or set the updated_at of existing items to the current date and time.
  • remove to remove card identifiers from the list
  • remove_not_updated_since to remove card identifiers based on their updated_at timestamp.
Authorizations:
triple_auth
Request Body schema: application/json
action
required
string

The action to take

required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
Example
{
  • "action": "remove",
  • "card_exclusions": [
    ]
}

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "content": {
    }
}

List Merchants

Returns a list of Merchants, optionally filtered.

This list can be used to find a Merchant's ID given an external ID. This endpoint has a limit of up to 100 merchants per page.

Authorizations:
triple_auth
query Parameters
merchant_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 100

The size of pages for returned Objects.

Responses

Response samples

Content type
application/json
{
  • "merchants": [
    ],
  • "total": 0
}

Create a Merchant

Creates a Merchant.

Authorizations:
triple_auth
Request Body schema: application/json
required
object (StrictAddress)

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.

assumed_name
required
string (MerchantAssumedName) [ 1 .. 100 ] characters

The (doing-business-as) name of the Merchant.

external_id
required
string (Merchant External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Merchant.

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 Merchant 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 (###-##-####).

merchant_category_code
required
string (MerchantCategoryCode) = 4 characters ^\d{4}$

The 4-digit Merchant Category Code

logo_url
string <url> (MerchantLogoUrl) <= 2000 characters ^https://.+$

A link to the merchant's logo

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "external_id": "string",
  • "merchant_category_code": "7998",
  • "logo_url": "string"
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "merchant_category": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "logo_url": "string",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a Merchant

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "merchant_category": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "logo_url": "string",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Merchant

Updates a Merchant with any of the values set in the request. The update takes an object with zero or more value definitions, each can be set to the value described in the spec or null. Invalid values will raise an error condition.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
assumed_name
string (MerchantAssumedName) [ 1 .. 100 ] characters

The (doing-business-as) name of the Merchant.

object (Address)

A physical address in the world. 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. NOTE: Though not marked as required, the street address, postal code, and country code are required for transaction matching to function properly.

merchant_category_code
string (MerchantCategoryCode) = 4 characters ^\d{4}$

The 4-digit Merchant Category Code

logo_url
string <url> (MerchantLogoUrl) <= 2000 characters ^https://.+$

A link to the merchant's logo

Responses

Request samples

Content type
application/merge-patch+json
{
  • "assumed_name": "string",
  • "address": {
    },
  • "merchant_category_code": "7998",
  • "logo_url": "string"
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "merchant_category": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "logo_url": "string",
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

List Merchant Locations

Returns a list of Merchant Locations, optionally filtered.

This list can be used to find a Merchant Location's ID given an external ID.

Authorizations:
triple_auth
query Parameters
merchant_location_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

page
integer
Default: 1

The page of results for returned Objects.

page_size
integer
Default: 100

The size of pages for returned Objects.

parent_merchant_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

Responses

Response samples

Content type
application/json
{
  • "locations": [
    ],
  • "total": 0
}

Create a Merchant Location

Creates a Merchant Location.

Authorizations:
triple_auth
Request Body schema: application/json
object (StrictAddress)

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.

email
string (MerchantLocationEmail) <= 200 characters ^(([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([...

An email address for the location.

external_id
required
string (Merchant Location External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Merchant Location.

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 Merchant Location 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 (###-##-####).

is_online
required
boolean (MerchantLocationIsOnline)

Indicates whether or not this is an online location.

location_name
string (MerchantLocationName) [ 0 .. 100 ] characters ^(?!\s)(.+)?(?<!\s)$

The name of the Merchant Location. If not specified, the Merchant name is used.

location_website
string (MerchantLocationWebsite) <= 2000 characters ^https:\/\/.+$

A URL for the location or online offer. Required if 'is_online' is true

parent_merchant_external_id
required
string (Merchant Location External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Merchant Location.

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 Merchant Location 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 (###-##-####).

phone_number
string (MerchantLocationPhoneNumber) <= 16 characters ^(([0-9]{3})?[-\s\.]?[(]?[0-9]{3}[)]?[-\s\.]?...

A phone number for the location.

Array of objects (ProcessorMerchantIds)

The Processor Merchant ID (MID) is an unique number used to identify the business for credit and debit card payment processing.

Physical locations and online retailers may have multiple MIDs, even for the same processor network, usually for different departments or checkouts.

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "email": "merchant.location@merchant.com",
  • "external_id": "string",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "parent_merchant_external_id": "string",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "email": "merchant.location@merchant.com",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "parent_merchant_external_id": "string",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ],
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a Merchant Location

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "address": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "email": "merchant.location@merchant.com",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "parent_merchant_external_id": "string",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ],
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Merchant Location

Updates a Merchant Location.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
object (Address)

A physical address in the world. 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. NOTE: Though not marked as required, the street address, postal code, and country code are required for transaction matching to function properly.

email
string (MerchantLocationEmail) <= 200 characters ^(([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([...

An email address for the location.

is_online
boolean (MerchantLocationIsOnline)

Indicates whether or not this is an online location.

location_name
string (MerchantLocationName) [ 0 .. 100 ] characters ^(?!\s)(.+)?(?<!\s)$

The name of the Merchant Location. If not specified, the Merchant name is used.

location_website
string (MerchantLocationWebsite) <= 2000 characters ^https:\/\/.+$

A URL for the location or online offer. Required if 'is_online' is true

phone_number
string (MerchantLocationPhoneNumber) <= 16 characters ^(([0-9]{3})?[-\s\.]?[(]?[0-9]{3}[)]?[-\s\.]?...

A phone number for the location.

Array of objects (ProcessorMerchantIds)

The Processor Merchant ID (MID) is an unique number used to identify the business for credit and debit card payment processing.

Physical locations and online retailers may have multiple MIDs, even for the same processor network, usually for different departments or checkouts.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "address": {
    },
  • "email": "merchant.location@merchant.com",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "email": "merchant.location@merchant.com",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "is_online": true,
  • "location_name": "string",
  • "location_website": "https://merchant-website.com",
  • "parent_merchant_external_id": "string",
  • "phone_number": "string",
  • "processor_merchant_ids": [
    ],
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Delete a Merchant Location

Deletes a Merchant Location

path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "content": {
    }
}

List Offers

Returns a list of Offers, optionally filtered.

This list can be used to find an Offer's ID given an external ID.

Authorizations:
triple_auth
query Parameters
merchant_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

offer_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID

Responses

Response samples

Content type
application/json
{
  • "offers": [
    ],
  • "total": 0
}

Create an Offer

Creates an Offer.

Authorizations:
triple_auth
Request Body schema: application/json
activation_required
required
boolean (OfferActivationIsRequired)

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.

activation_duration_in_days
required
number or null (OfferActivationInDays)

If specified, the number of days (inclusive) for which an offer activation is valid.

If a transaction falls outside of this duration, it will not qualify for the offer. The day of activation is considered day 1. So, if a cardholder activates an offer on Monday with a 3 day duration, they must make their transaction on or before Wednesday.

allowed_card_program_ids
Array of strings (OfferAllowedCardProgramIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will only be available for the card program id(s) supplied.

allowed_portfolio_manager_ids
Array of strings (OfferAllowedPortfolioManagerIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will only be available for the portfolio manger id(s) supplied.

allowed_publisher_ids
Array of strings (OfferAllowedPublisherIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will only be available for the publishers id(s) supplied.

category
required
string (TripleOfferCategory)
Enum: "AUTOMOTIVE" "CHILDREN_AND_FAMILY" "ELECTRONICS" "ENTERTAINMENT" "FINANCIAL_SERVICES" "FOOD" "HEALTH_AND_BEAUTY" "HOME" "OFFICE_AND_BUSINESS" "RETAIL" "SERVICES_AND_SUBSCRIPTIONS" "TRAVEL" "UTILITIES_AND_TELECOM"

triple Offer Category

currency_code
required
string (OfferCurrencyCode) = 3 characters ^[A-Z]{3}$
Default: "USD"

The currency for the offer reward, minimum spend requirement, and maximum reward limitations. The value is an ISO-4217 currency code.

denied_card_program_ids
Array of strings (OfferDeniedCardProgramIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will be denied for the card program id(s) supplied.

denied_portfolio_manager_ids
Array of strings (OfferDeniedPortfolioManagerIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will be denied for the portfolio manger id(s) supplied.

denied_publisher_ids
Array of strings (OfferDeniedPublisherIds) [ items [ 1 .. 100 ] characters ]

If specified, the offer will be denied for the publishers id(s) supplied.

effective_date
required
string <date> (OfferEffectiveDate)

The first date on which the offer is valid.

excluded_dates
Array of strings <date> (OfferExcludedDates) [ items <date > ]

Dates for which the offer is not valid. Transactions made on these dates will not qualify for a reward.

expiration_date
required
string or null <date> (OfferExpirationDate)

If specified, the last date on which the offer is valid.

external_id
required
string (Offer External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

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 (###-##-####).

description
required
string (OfferDescription) [ 6 .. 65535 ] characters

A long-form text description of or promotional content for an offer

headline
required
string (OfferHeadline) [ 6 .. 100 ] characters

The headline or title for the offer, appropriate for top-level display.

object (OfferInvalidDayParts)

If specified, the days of the week and times during which the offer is invalid.

marketing_fee_currency_code
required
string or null (OfferMarketingFeeCurrencyCode) = 3 characters ^[A-Z]{3}$
Default: "USD"

The ISO-3166 label for marketing currency. Defaults to 'USD' if omitted or null.

marketing_fee_rate
required
number or null (OfferMarketingFeeRate)

The share percentage if this offer has a marketing_fee_type of percentage, the amount will be between 0.0 and 100.0

marketing_fee_type
required
string (OfferMarketingFeeType)
Enum: "FIXED" "PERCENTAGE"
marketing_fee_value
required
number (OfferMarketingFeeValue)

The fixed share value if this offer has a marketing_fee_type of fixed, the amount must be greater than or equal to 0.

maximum_redemptions
required
string or null (OfferMaximumRedemptions) ^\d{1,3}\/\d{1,3}[YMWD]$

The maximum number of times a cardholder may receive a reward for this offer over a given period of time.

The numerator of this value is the number of times a reward can be earned. The numerator must be less than 1000. The denominator is the period of time over which the limit is enforced.

Time periods must conform to the following restrictions:

  • a period of years (Y) must be 1-3
  • a period of months (M) must be 1-36
  • a period of weeks (W) must be 1-156
  • a period of days (D) must be 1-365
maximum_reward_cumulative
required
string or null (OfferMaximumRewardCumulative) ^\d{1,12}\/\d{1,3}[YMWD]$

The maximum monetary value a cardholder may earn for this offer across multiple transactions over a given period of time.

The numerator of this value is the maximum monetary value a reward can earn. The numerator must be less than 1000000000000. The denominator is the period of time over which the limit is enforced.

Time periods must conform to the following restrictions:

  • a period of years (Y) must be 1-3
  • a period of months (M) must be 1-36
  • a period of weeks (W) must be 1-156
  • a period of days (D) must be 1-365
maximum_reward_per_transaction
required
number or null (OfferMaximumRewardPerTransaction) > 0

The maximum monetary value a cardholder may earn for a percentage-based reward on any single transaction.

required
Array of objects or null (OfferMerchantCategories) [ 1 .. 25 ] items

The Merchant Category Codes included for a categorical offer.

merchant_external_id
required
string (EntityId) [ 1 .. 100 ] characters

The triple-defined ID for the entity.

merchant_website
required
string or null <url> (MerchantWebsite) <= 2000 characters ^https://.+$
minimum_spend
required
number (OfferMinimumSpend) >= 0

The minimum monetary value that a cardholder must spend for a transaction to qualify for this offer.

mode
required
string (OfferMode)
Enum: "ONLINE" "IN_PERSON"

The offer delivery mode

object (OfferBudgetRequest)
offer_type
required
string (OfferType)
Enum: "CARD_LINKED" "AFFILIATE" "CATEGORICAL"

The type of offer - card-linked, affiliate, categorical, etc.

reward_rate
required
number or null (OfferRewardRate) > 0

The reward percentage if this offer has a reward_type of percentage, the amount will be between 0.0 and 100.0

reward_type
required
string (OfferRewardType)
Enum: "FIXED" "PERCENTAGE"

Indicates whether this offer is for a fixed or percentage-based amount.

reward_value
required
number or null (OfferRewardValue) > 0

The fixed reward value if this offer has a reward_type of fixed, the amount must be greater than or equal to 0.

terms
required
string or null (OfferTermsAndConditions)

Terms and conditions for the offer, not inclusive of other limits specified by the offer properties, such as minimum spend, excluded dates, or activation requirements.

required
object (OfferValidDayParts)

If specified, the days of the week and times during which the offer is valid. If unspecified, the offer is valid for all days and times during the week.

Responses

Request samples

Content type
application/json
{
  • "activation_required": true,
  • "activation_duration_in_days": 0,
  • "allowed_card_program_ids": [
    ],
  • "allowed_portfolio_manager_ids": [
    ],
  • "allowed_publisher_ids": [
    ],
  • "category": "AUTOMOTIVE",
  • "currency_code": "USD",
  • "denied_card_program_ids": [
    ],
  • "denied_portfolio_manager_ids": [
    ],
  • "denied_publisher_ids": [
    ],
  • "effective_date": "2021-12-01",
  • "excluded_dates": [
    ],
  • "expiration_date": "2021-12-31",
  • "external_id": "string",
  • "description": "string",
  • "headline": "string",
  • "invalid_day_parts": {
    },
  • "marketing_fee_currency_code": "USD",
  • "marketing_fee_rate": 0,
  • "marketing_fee_type": "FIXED",
  • "marketing_fee_value": 0,
  • "maximum_redemptions": "1/3M",
  • "maximum_reward_cumulative": "1/3M",
  • "maximum_reward_per_transaction": 0,
  • "merchant_categories": [
    ],
  • "merchant_external_id": "triple-abc-123",
  • "merchant_website": "string",
  • "minimum_spend": 0,
  • "mode": "ONLINE",
  • "offer_budget": {
    },
  • "offer_type": "CARD_LINKED",
  • "reward_rate": 0,
  • "reward_type": "FIXED",
  • "reward_value": 0,
  • "terms": "string",
  • "valid_day_parts": {
    }
}

Response samples

Content type
application/json
{
  • "activation_duration_in_days": 0,
  • "activation_required": true,
  • "category": "AUTOMOTIVE",
  • "category_tags": "string",
  • "currency_code": "USD",
  • "description": "string",
  • "effective_date": "2021-12-01",
  • "excluded_dates": [
    ],
  • "expiration_date": "2021-12-31",
  • "external_id": "string",
  • "headline": "string",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "invalid_day_parts": {
    },
  • "logo_url": "string",
  • "marketing_fee_currency_code": "USD",
  • "marketing_fee_rate": 0,
  • "marketing_fee_value": 0,
  • "marketing_fee_type": "FIXED",
  • "maximum_redemptions": "1/3M",
  • "maximum_reward_cumulative": "1/3M",
  • "maximum_reward_per_transaction": 0,
  • "merchant_categories": [
    ],
  • "merchant_website": "string",
  • "minimum_spend": 0,
  • "offer_budget": {
    },
  • "offer_mode": "ONLINE",
  • "offer_type": "CARD_LINKED",
  • "reward_rate": 0,
  • "reward_type": "FIXED",
  • "reward_value": 0,
  • "terms_and_conditions": "string",
  • "valid_day_parts": {
    }
}

Get an Offer

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "activation_duration_in_days": 0,
  • "activation_required": true,
  • "category": "AUTOMOTIVE",
  • "category_tags": "string",
  • "currency_code": "USD",
  • "description": "string",
  • "effective_date": "2021-12-01",
  • "excluded_dates": [
    ],
  • "expiration_date": "2021-12-31",
  • "external_id": "string",
  • "headline": "string",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "invalid_day_parts": {
    },
  • "logo_url": "string",
  • "marketing_fee_currency_code": "USD",
  • "marketing_fee_rate": 0,
  • "marketing_fee_value": 0,
  • "marketing_fee_type": "FIXED",
  • "maximum_redemptions": "1/3M",
  • "maximum_reward_cumulative": "1/3M",
  • "maximum_reward_per_transaction": 0,
  • "merchant_categories": [
    ],
  • "merchant_website": "string",
  • "minimum_spend": 0,
  • "offer_budget": {
    },
  • "offer_mode": "ONLINE",
  • "offer_type": "CARD_LINKED",
  • "reward_rate": 0,
  • "reward_type": "FIXED",
  • "reward_value": 0,
  • "terms_and_conditions": "string",
  • "valid_day_parts": {
    }
}

Update an Offer

Updates an Offer.

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Request Body schema: application/merge-patch+json
category
string (TripleOfferCategory)
Enum: "AUTOMOTIVE" "CHILDREN_AND_FAMILY" "ELECTRONICS" "ENTERTAINMENT" "FINANCIAL_SERVICES" "FOOD" "HEALTH_AND_BEAUTY" "HOME" "OFFICE_AND_BUSINESS" "RETAIL" "SERVICES_AND_SUBSCRIPTIONS" "TRAVEL" "UTILITIES_AND_TELECOM"

triple Offer Category

expiration_date
string or null <date> (OfferExpirationDate)

If specified, the last date on which the offer is valid.

headline
string (OfferHeadline) [ 6 .. 100 ] characters

The headline or title for the offer, appropriate for top-level display.

Array of objects or null (OfferMerchantCategories) [ 1 .. 25 ] items

The Merchant Category Codes included for a categorical offer.

merchant_website
string or null <url> (MerchantWebsite) <= 2000 characters ^https://.+$

Responses

Request samples

Content type
application/merge-patch+json
{
  • "category": "AUTOMOTIVE",
  • "expiration_date": "2021-12-31",
  • "headline": "string",
  • "merchant_categories": [
    ],
  • "merchant_website": "string"
}

Response samples

Content type
application/json
{
  • "activation_duration_in_days": 0,
  • "activation_required": true,
  • "category": "AUTOMOTIVE",
  • "category_tags": "string",
  • "currency_code": "USD",
  • "description": "string",
  • "effective_date": "2021-12-01",
  • "excluded_dates": [
    ],
  • "expiration_date": "2021-12-31",
  • "external_id": "string",
  • "headline": "string",
  • "id": "triple-abc-123",
  • "is_activated": true,
  • "invalid_day_parts": {
    },
  • "logo_url": "string",
  • "marketing_fee_currency_code": "USD",
  • "marketing_fee_rate": 0,
  • "marketing_fee_value": 0,
  • "marketing_fee_type": "FIXED",
  • "maximum_redemptions": "1/3M",
  • "maximum_reward_cumulative": "1/3M",
  • "maximum_reward_per_transaction": 0,
  • "merchant_categories": [
    ],
  • "merchant_website": "string",
  • "minimum_spend": 0,
  • "offer_budget": {
    },
  • "offer_mode": "ONLINE",
  • "offer_type": "CARD_LINKED",
  • "reward_rate": 0,
  • "reward_type": "FIXED",
  • "reward_value": 0,
  • "terms_and_conditions": "string",
  • "valid_day_parts": {
    }
}

Delete and Offer

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "content": {
    }
}

Portfolio Management

Operations related to managing Portfolios of Publishers.

Partners who manage Card Programs for multiple Publishers may wish to organize those Publishers into Portfolios. Portfolios allow Offer Exclusions to be applied across multiple Publishers without having to add each Publisher to each Offer Exclusion.

Get a list of Publishers

Returns a list of Publishers, optionally filtered.

Currently, this endpoint has a hard limit of returning up to 1,000 results. Future API releases may support paging results.

Authorizations:
triple_auth
query Parameters
publisher_external_id
string [ 1 .. 255 ] characters

Partner-provided external ID of a Publisher. This parameter is ignored unless the client is a Portfolio Manager.

Responses

Response samples

Content type
application/json
{
  • "publishers": [
    ],
  • "total": 0
}

Create a Publisher

Authorizations:
triple_auth
Request Body schema: application/json
required
object (StrictAddress)

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.

assumed_name
required
string (PublisherAssumedName) [ 1 .. 100 ] characters ^(?!\s).+(?<!\s)$

Assumed legal name of the Publisher

external_id
required
string (Publisher External ID) [ 1 .. 255 ] characters ^(?!\d{3}-\d\d-\d{4}$)

Partner-provided, external ID for a Publisher.

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 Publisher within the scope of its parent Portfolio Manager.

To protect against accidental inclusion of sensitive personal information, external IDs may not be 9-digit numbers or use the US Tax ID format (###-##-####).

revenue_share
number (PublisherRevenueShare) [ 0 .. 100 ]

The percent-based revenue share of this Publisher.

Only Portfolio Managers may set this value for their Publishers. If set, this will override the value set at the Portfolio Manager level.

Responses

Request samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "external_id": "string",
  • "revenue_share": 1.125
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "portfolio_manager_id": "triple-abc-123",
  • "revenue_share": 1.125,
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Get a Publisher

Authorizations:
triple_auth
path Parameters
id
required
string (EntityId) [ 1 .. 100 ] characters
Example: triple-abc-123

The triple-defined ID for the entity.

Responses

Response samples

Content type
application/json
{
  • "address": {
    },
  • "assumed_name": "string",
  • "created_at": "2021-12-01T01:59:59.000Z",
  • "external_id": "string",
  • "id": "triple-abc-123",
  • "portfolio_manager_id": "triple-abc-123",
  • "revenue_share": 1.125,
  • "updated_at": "2021-12-01T01:59:59.000Z"
}

Update a Publisher

Updates a Publisher.

Currently, only the Publisher name and address may be updated.<