# Tremendous API Documentation > Tremendous' API lets you send gift cards and rewards programmatically, in bulk, all over the world. ## Guides - [Introduction](https://developers.tremendous.com/docs/introduction.md): Manage rewards and payouts at scale - [3) Send your first reward](https://developers.tremendous.com/docs/3-sending-your-first-reward.md): Exercise your newfound powers. - [Postman Collection](https://developers.tremendous.com/docs/postman-collection.md): Integrate the Tremendous API using our Postman Collection. - [Sandbox environment](https://developers.tremendous.com/docs/sandbox-environment.md): Learn about available API environments. - [Creating multi-product rewards](https://developers.tremendous.com/docs/creating-multi-product-rewards-wip.md): Let recipients choose from a wide set of payout options. - [Creating single-product rewards](https://developers.tremendous.com/docs/creating-single-product-rewards.md): Send a prepaid card, an Amazon.com gift card, or any other product in our catalog. - [Email delivery](https://developers.tremendous.com/docs/emailing-rewards.md): Tremendous emails your recipient - [Obtaining links](https://developers.tremendous.com/docs/link-delivery.md): Obtain a link that you can deliver yourself - [SMS delivery](https://developers.tremendous.com/docs/sms-rewards-wip.md) - [Customizing rewards using campaigns](https://developers.tremendous.com/docs/personalize-and-style-your-rewards.md): Using campaigns to control the look and feel of the rewards you send. - [Setting reward copy without campaigns](https://developers.tremendous.com/docs/personalizing-rewards-without-campaigns.md) - [OAuth 2.0](https://developers.tremendous.com/docs/oauth-20.md): Make API calls on behalf of other Tremendous users - [Tremendous Connect](https://developers.tremendous.com/docs/tremendous-connect.md): Embedded experience for your clients to connect to Tremendous through your platform - [Funding your account](https://developers.tremendous.com/docs/paying-for-orders.md): An overview of ways to pay. - [Paying for orders](https://developers.tremendous.com/docs/paying-for-orders-1.md) - [Managing your balance](https://developers.tremendous.com/docs/managing-your-balance.md) - [Adding custom data to rewards](https://developers.tremendous.com/docs/using-custom-fields-to-add-custom-data-to-rewards.md): Using the Custom Fields feature, programmatically. - [Managing currencies](https://developers.tremendous.com/docs/handling-currencies.md) - [Error handling](https://developers.tremendous.com/docs/error-handling.md): Status codes and the error object. - [Webhooks](https://developers.tremendous.com/docs/webhooks-1.md) - [Reward delivery failed](https://developers.tremendous.com/docs/delivery-failure-payload.md) - [Change management](https://developers.tremendous.com/docs/versioning.md) - [Production access](https://developers.tremendous.com/docs/production-api-access.md) ## API Reference - [Rewards](https://developers.tremendous.com/reference/rewards.md) - [Reward schema](https://developers.tremendous.com/reference/obj-schema-rewards.md) - [List rewards](https://developers.tremendous.com/reference/list-rewards.md): Retrieve a list of all created rewards. You can query for rewards by custom field attributes using the field label and values as query params. [Learn more](https://developers.tremendous.com/docs/using-custom-fields-to-add-custom-data-to-rewards#querying-by-custom-fields) - [Retrieve single reward](https://developers.tremendous.com/reference/get-reward.md): Retrieve the reward, identified by the given `id` in the URL - [Generate a reward URL](https://developers.tremendous.com/reference/generate-reward-link.md): Generate a redemption link for the reward identified by the `id` in the URL - [Resend reward](https://developers.tremendous.com/reference/resend-reward.md): Resends a reward, identified by the given `id` in the URL, to its recipient. Only rewards with a previous delivery failure can be resent. - [Cancel reward](https://developers.tremendous.com/reference/cancel-reward.md): Cancels a reward, identified by the given `id` in the URL. Only non-expired rewards with a delivery failure can be canceled. - [Orders](https://developers.tremendous.com/reference/orders.md) - [Order schema](https://developers.tremendous.com/reference/obj-schema-orders-1.md) - [List orders](https://developers.tremendous.com/reference/list-orders.md): Retrieve a list of orders - [Create order](https://developers.tremendous.com/reference/create-order.md): Every time you want to send out a reward through Tremendous you need to create an order for it. > ๐Ÿ“˜ Getting started with your first order > > Our step-by-step guide walks you through everything you need > to send your first gift card through the Tremendous API: > > Check it out! ## Request body
Property Type Description
external_id
string

Reference for this order, supplied by the customer.

When set, external_id makes order idempotent. All requests that use the same external_id after the initial order creation, will result in a response that returns the data of the initially created order. The response will have a 201 response code. These responses fail to create any further orders.

It also allows for retrieving by external_id instead of id only.

payment
object
Show object properties
Property Type Description
funding_source_id
string

Tremendous ID of the funding source that will be used to pay for the order. Use balance to use your Tremendous's balance.
reward
object

A single reward, sent to a recipient. A reward is always part of an order.

Either products or campaign_id must be specified.

Show object properties
Property Type Description
id
string

Tremendous ID of the reward

order_id
string

Tremendous ID of the order this reward is part of.

created_at
string date-time

Date the reward was created

expires_at
string date-time

Expiration date of the reward. If null, the reward does not expire.

campaign_id
string

ID of the campaign in your account, that defines the available products (different gift cards, charity, etc.) that the recipient can choose from.

products
array string

List of IDs of product (different gift cards, charity, etc.) that will be available to the recipient to choose from.

Providing a products array will override the products made available by the campaign specified using the campaign_id property unless the products array is empty. It will not override other campaign attributes, like the message and customization of the look and feel.

value
object
Show object properties
Property Type Description
denomination
number double

Amount of the reward

currency_code
string

Currency of the reward. Defaults to the organization's currency if not provided.
recipient
object

Details of the recipient of the reward

Show object properties
Property Type Description
name
string

Name of the recipient

email
string

Email address of the recipient

phone
string

Phone number of the recipient. For non-US phone numbers, specify the country code (prefixed with +).
deliver_at
string date

Timestamp of reward delivery within the next year. Note that if date-time is provided, the time values will be ignored.

custom_fields
array
Show array item type
Property Type Description
id
string

Tremendous ID of the custom field

value
string

Value of the custom field

label
string

Label of the custom field
language
string

Set this to translate the redemption experience for this reward. Pass a 2-letter ISO-639-1 code for the desired language. Defaults to en.

delivery
object

Details on how the reward is delivered to the recipient.

Show object properties
Property Type Description
method
string

How to deliver the reward to the recipient.

Delivery Method Description
EMAIL Deliver the reward to the recipient by email
LINK

Deliver the reward to the recipient via a link.

The initial POST /orders response for a link reward includes the link in delivery.link.

The link must then be delivered to the recipient out-of-band.

To obtain a new link for an existing reward, call POST /rewards/{id}/generate_link.
PHONE Deliver the reward to the recipient by SMS
meta
object

Customizable reward delivery metadata, taking precedence over the related campaign settings.

Show object properties
Property Type Description
sender_name
string

The "sender name" used in the delivery. If it's an email reward, "via Tremendous" will be appended to the value. Please note that you cannot customize the sender email.

subject_line
string

The subject line used in the delivery.

message
string

The content of the message of the reward, shown in the email / SMS and on the landing page.
### Funding sources There are different ways to pay for gift cards and rewards on Tremendous. Every payment mechanism is called a "funding source". You can retrieve a list of all available funding sources by using the [Funding sources API endpoint](https://developers.tremendous.com/reference/list-funding-sources). The Tremendous API sandbox environment comes with a single funding source that allows you to spend up to $100,000 in *fake money* to test the API. [Learn more about the sandbox environment](https://developers.tremendous.com/docs/sandbox-environment). The HTTP status code `200` on the response will be used to indicate success. After processing successfully the reward gets queued to be delivered to it's recipient (for delivery method `EMAIL` and `PHONE`). Delivery will happen asynchronously, after the response has been sent. ### Idempotence Requests issued with the same `external_id` are idempotent. Submitting an order with an already existing `external_id` will not create a new order. If the payload is the same as a previously issued order, our API will return a `201` response code, along with a representation of the already-existing order in the response body. If the `external_id` used is for an order with different parameters (e.g. amount, recipient), our API will return a `409` response code, indicating a conflicting resource. - [Retrieve order](https://developers.tremendous.com/reference/get-order.md): Retrieve the order, identified by the given `id` in the URL - [Approve order](https://developers.tremendous.com/reference/approve-order.md): Approves an order that is pending review, identified by the given `id` in the URL. Approvals is a feature that requires orders to be approved by an organization admin before they are sent out. To enable approvals for your organization, please enable 'Allow approvals via API' via the organization''s 'Order Approvals' settings from the Tremendous dashboard. - [Reject order](https://developers.tremendous.com/reference/reject-order.md): Rejects an order that is pending review, identified by the given `id` in the URL. Approvals is a feature that requires orders to be approved by an organization admin before they are sent out. To enable approvals for your organization, please enable 'Allow approvals via API' via the organization''s 'Order Approvals' settings from the Tremendous dashboard. - [Products](https://developers.tremendous.com/reference/products.md) - [Product schema](https://developers.tremendous.com/reference/obj-schema-products-1.md) - [List products](https://developers.tremendous.com/reference/list-products.md): Retrieve a list of available products - [Retrieve product](https://developers.tremendous.com/reference/get-product.md): Retrieve a product, identified by the given `id` in the URL - [Campaigns](https://developers.tremendous.com/reference/campaigns.md) - [Campaign schema](https://developers.tremendous.com/reference/obj-schema-campaigns-1.md) - [List campaigns](https://developers.tremendous.com/reference/list-campaigns.md): Retrieve a list of all campaigns created in your account - [Create campaign](https://developers.tremendous.com/reference/create-campaign.md) - [Retrieve campaign](https://developers.tremendous.com/reference/get-campaign.md): Retrieve a campaign, identified by the given `id` in the URL - [Update campaign](https://developers.tremendous.com/reference/update-campaign.md) - [Funding sources](https://developers.tremendous.com/reference/funding-sources.md) - [Funding source schema](https://developers.tremendous.com/reference/obj-schema-funding-sources-1.md) - [List funding sources](https://developers.tremendous.com/reference/list-funding-sources.md): Retrieve a list of all funding sources in your organization's account. - [Retrieve funding source](https://developers.tremendous.com/reference/get-funding-source.md): Retrieve a funding source, identified by the given `id` in the URL. You can also use the special keyword `BALANCE` (case-insensitive) to retrieve the organization's balance funding source. - [Invoices](https://developers.tremendous.com/reference/invoices-1.md) - [Invoice schema](https://developers.tremendous.com/reference/obj-schema-invoices-1.md) - [List invoices](https://developers.tremendous.com/reference/list-invoices.md): Fetch a list of all invoices on your account. > ๐Ÿšง Deleted invoices are omitted > > The response does not include any previously deleted invoices. - [Create invoice](https://developers.tremendous.com/reference/create-invoice.md): Creating an invoice is the way for your organization to fund your account's balance. 1. Create an invoice 2. Pay the invoice 3. Funds get added to your account's balance ## Request body
Property Type Description
po_number
string

Reference to the purchase order number within your organization

amount
number double

Amount of the invoice

currency_code
string

Currency of the invoice. Defaults to the organization's currency if not provided.

memo
string

A note to be included in the invoice. This is for your internal use and will not be visible to the recipient.
- [Retrieve invoice](https://developers.tremendous.com/reference/get-invoice.md): Retrieve an invoice, identified by the given `id` in the URL > ๐Ÿ“˜ Deleted Invoices > > This endpoint can be used to retrieve details on deleted invoices > that the list of invoices omits. - [Delete invoice](https://developers.tremendous.com/reference/delete-invoices.md): Removes an invoice. This has no further consequences but is a rather cosmetic operation. - [Retrieve invoice as PDF](https://developers.tremendous.com/reference/download-invoice-pdf.md): Generates a PDF version for an invoice - [Retrieve invoice as CSV](https://developers.tremendous.com/reference/download-invoice-csv.md): Generates a CSV version for an invoice listing the associated rewards and orders - [Topups](https://developers.tremendous.com/reference/topups.md) - [Topup schema](https://developers.tremendous.com/reference/obj-schema-topups-1.md) - [List topups](https://developers.tremendous.com/reference/list-topups.md): Retrieve a list of all topup requests. - [Create a topup](https://developers.tremendous.com/reference/create-topup.md) - [Retrieve single topup](https://developers.tremendous.com/reference/get-topup.md): Retrieve a topup, identified by the given `id` in the URL. - [Balance transactions](https://developers.tremendous.com/reference/balance-transactions.md) - [Balance transaction schema](https://developers.tremendous.com/reference/obj-schema-balance-transactions-1.md) - [List balance transactions](https://developers.tremendous.com/reference/list-balance-transactions.md): Fetch a list of all balance transactions on your account. - [Organizations](https://developers.tremendous.com/reference/organizations.md) - [Organization schema](https://developers.tremendous.com/reference/obj-schema-organizations-1.md) - [List organizations](https://developers.tremendous.com/reference/list-organizations.md): The returned list only includes the organization to which the API key belongs to, that is used for the request. - [Create organization](https://developers.tremendous.com/reference/create-organization.md): Organizations are a way to separate different parts of your business within the same Tremendous account. You can assign users in your Tremendous team as members to any organization. Users can be members of multiple organizations at once. API keys belong to a single organization. The API key used in a request determines on behalf of which organization the request is carried out. **Important note:** When creating an organization, you are required to either pass `with_api_key` or `copy_settings[user]` in the request body as `true`. This ensures that your new Organization can either be accessed via the API or the Dashboard. - [Create API key](https://developers.tremendous.com/reference/create-api-key.md): Creates a new API key. The API key used to make the request will remain active. Created API keys are generated randomly and returned in the response. **You cannot retrieve them again.** - [Members](https://developers.tremendous.com/reference/members-1.md) - [Member schema](https://developers.tremendous.com/reference/obj-schema-members-1.md) - [List members](https://developers.tremendous.com/reference/list-members.md): To list members of a sub-organization [create an API key for that organization](/reference/post_organizations-id-create-api-key) first, then use the new API key in the list members request. - [Create member](https://developers.tremendous.com/reference/create-member.md): Each organization has one or more users that can access and manage that organization. These users are called members. Members can take actions via the Tremendous web dashboard directly. These actions include adding funding sources to the organization, creating Campaigns, and more. ### Permissions Members can have a role that determine their permissions within the organization. Check the Roles API for the available roles. To create members of a sub-organizations [create an API key for that organization](/reference/post_organizations-id-create-api-key) first, then use the new API key in the create member request. ### Inviting new members After creating a member, an automatic invite is sent to the email address. If the user is not registered yet, that person will then need to sign up for a Tremendous account. > โ—๏ธ Automatic invitations are not available in the sandbox > > You must manually use the returned `invite_url` field in the payload instead. - [Retrieve member](https://developers.tremendous.com/reference/get-member.md) - [Update member](https://developers.tremendous.com/reference/update-member.md): Updates the role of an existing member, identified by the given `id` in the URL. Check the Roles API for the roles available within the organization. - [Delete member](https://developers.tremendous.com/reference/delete-member.md): Removes an existing member from the organization, identified by the given `id` in the URL. The member loses access to the organization and a `MEMBERS.DELETED` webhook event is emitted. - [Roles](https://developers.tremendous.com/reference/roles.md) - [Role schema](https://developers.tremendous.com/reference/obj-schema-roles-1.md) - [List roles](https://developers.tremendous.com/reference/list-roles.md): List all available roles in the organization. - [Fields](https://developers.tremendous.com/reference/fields.md) - [Field schema](https://developers.tremendous.com/reference/obj-schema-fields-1.md) - [List fields](https://developers.tremendous.com/reference/list-fields.md): For reporting and analytics purposes, custom fields can be associated with rewards generated through the API. Custom fields must be first added by members of your admin team through the Tremendous Dashboard. - [Create field](https://developers.tremendous.com/reference/create-field.md): Create a custom field to be associated with rewards. Custom fields can be used for reporting and analytics purposes. - [Webhooks](https://developers.tremendous.com/reference/webhooks.md) - [Webhook schema](https://developers.tremendous.com/reference/obj-schema-webhooks-1.md) - [List webhooks](https://developers.tremendous.com/reference/list-webhooks.md): Every organization can only have one webhook. This endpoint shows the details about that webhook. > ๐Ÿ“˜ Learn more about Webhooks > > Our guide explains everything you need to know about the Tremendous webhooks: > [Read it here](/docs/webhooks-1) - [Create webhook](https://developers.tremendous.com/reference/create-webhook.md): Tremendous uses webhooks as a notification system for various events that happen in your account. > ๐Ÿ“˜ Learn more about Webhooks > > Our guide explains everything you need to know about the Tremendous webhooks: > [Read it here](/docs/webhooks-1) Every organization can define a single webhook endpoint where we send requests to, whenever an event happens. This endpoint allows you to setup that endpoint. The URL of the endpoint can be changed by making a request to this endpoint again with the new URL. ## Request body
Property Type Description
url
string uri

URL the webhook will make requests to
- [Retrieve webhook](https://developers.tremendous.com/reference/get-webhook.md): > ๐Ÿ“˜ Learn more about Webhooks > > Our guide explains everything you need to know about the Tremendous webhooks: > [Read it here](/docs/webhooks-1) - [Delete webhook](https://developers.tremendous.com/reference/delete-webhook.md): > ๐Ÿ“˜ Learn more about Webhooks > > Our guide explains everything you need to know about the Tremendous webhooks: > [Read it here](/docs/webhooks-1) - [Test webhook](https://developers.tremendous.com/reference/simulate-webhook.md): Making a request to this endpoint will cause our system to trigger a webhook for the specified event. This can be very useful when testing the setup that processes webhooks on your end. > ๐Ÿ“˜ Learn more about Webhooks > > Our guide explains everything you need to know about the Tremendous webhooks: > [Read it here](/docs/webhooks-1) - [List events](https://developers.tremendous.com/reference/list-webhook-events.md): Lists all event types that can be sent to the configured webhook endpoint. > ๐Ÿ“˜ Learn more about Webhooks > > Our guide explains everything you need to know about the Tremendous webhooks: > [Read it here](/docs/webhooks-1) - [List exchange rates](https://developers.tremendous.com/reference/list-forex.md): Retrieve a list of exchange rates - [Fraud reviews](https://developers.tremendous.com/reference/fraud-reviews.md) - [Fraud review schema](https://developers.tremendous.com/reference/obj-schema-fraud-reviews-1.md) - [List fraud reviews](https://developers.tremendous.com/reference/list-fraud-reviews.md): Retrieve a paginated list of all fraud reviews. List can be filtered by status, created or redeemed at dates. - [Retrieve single fraud review](https://developers.tremendous.com/reference/get-fraud-review.md): Retrieve the details of a fraud review, identified by the given `id` in the URL. Returns additional details regarding the fraud review beyond what's provided in the List fraud reviews endpoint, including reward details, recipient geolocation, etc. - [Release fraud review](https://developers.tremendous.com/reference/release-fraud-review.md): Completes the fraud review identified by the given `id` in the URL, and releases the associated reward to the recipient. - [Block fraud review](https://developers.tremendous.com/reference/block-fraud-review.md): Completes the fraud review identified by the given `id` in the URL, and blocks the reward. The reward is canceled and the amount refunded. - [Fraud rules](https://developers.tremendous.com/reference/fraud-rules.md) - [List fraud rules](https://developers.tremendous.com/reference/list-fraud-rules.md): List active fraud rules associated with the organization tied to your API key. - [Configure fraud rule](https://developers.tremendous.com/reference/fraud-rule.md): Configure a fraud rule of the type passed in the URL. If a rule of the same type already exists, it will be overwritten. - [Delete fraud rule](https://developers.tremendous.com/reference/delete-fraud-rule.md): Deletes the rule of the type passed in the URL. - [Update fraud rule list](https://developers.tremendous.com/reference/update-fraud-rule-list.md): Use this endpoint to modify a list associated with an already-configured rule. Add and remove operations supported. For example, to append new IPs to the `review_ip` rule, a valid JSON body would be: ```json { "operation": "add", "config": { "ips": ["123.123.123.123"] } } ``` - [Reports](https://developers.tremendous.com/reference/reports.md) - [Report schema](https://developers.tremendous.com/reference/obj-schema-reports-1.md) - [Create report](https://developers.tremendous.com/reference/create-report.md): Creating a report allows your organization to programmatically retrieve information that's available in our dashboard UI. This request creates a new report object with a unique ID, and kicks off an async report generation. To retrieve a completed report, either poll `/api/v2/reports/{id}` or listen for REPORTS webhook event. ## Request body
Property Type Description
report_type
string

Type of report for retrieval.
Report type Description
digital_rewards Report for Tremendous digital reward history

format
string

Format the report will be generated in.
Format Description
csv CSV format for report

filters
object

Filters to apply to the report. Corresponds to the filters provided in the dashboard

Show object properties
Property Type Description
digital_rewards
object

Filters object for a report_type: digital_rewards report

Show object properties
Property Type Description
amount
object

Amount of the rewards returned in the report

Show object properties
Property Type Description
gte
number double

Minimum amount of the rewards that should be returned in the report

lte
number double

Maximum amount of the rewards that should be returned in the report
campaign_id
string

ID of the Tremendous campaign that this report should be limited to

created_at
object

Creation dates of rewards returned in the report

Show object properties
Property Type Description
gte
string date

Minimum date the reward was created

lte
string date

Maximum date the reward was created
delivered_at
string date

Delivery date for gifts that should be returned in the report

delivery_method
string

Delivery method for rewards returned in the report

order_id
string

ID of the Tremendous order that this report should be limited to

order_status
string

Order status for rewards returned in the report

status
array string

Status for rewards returned in the report
## Rate limits Some reports may take a long time to generate and we limit the number of reports that can be simultaneously generated by an organization at a given time. If you exceed the rate limit, you'll receive a `429` response. - [Retrieve report](https://developers.tremendous.com/reference/get-report.md): Retrieve the report, identified by the given `id` in the URL Using the ID that was returned by `POST /api/v2/reports`, retrieves a download link for the report, identified by the givenย IDย in the URL. Returns the reportโ€™s current status and, if available, the URL for download. The URL is valid for 7 days. - [Connected organizations](https://developers.tremendous.com/reference/connected-organizations.md) - [Connected organization schema](https://developers.tremendous.com/reference/obj-schema-connected-organizations.md) - [List connected organizations](https://developers.tremendous.com/reference/list-connected-organizations.md): Retrieve a list of connected organizations. - [Create connected organization](https://developers.tremendous.com/reference/create-connected-organization.md): Create a connected organization. Optionally pass a `kyb_prefill` object to forward KYB (Know Your Business) details you have already collected for the end client. When provided, these values prefill the end client's onboarding form; the end client still reviews, edits where needed, and submits the form. Every `kyb_prefill` field is optional, but any value provided is validated. Malformed KYB details (for example an unsupported `country_code` or a malformed `website_url`) return a `400`. - [Retrieve a connected organization](https://developers.tremendous.com/reference/get-connected-organization.md): Retrieve the connected organization, identified by the given `id` in the URL - [Delete a connected organization](https://developers.tremendous.com/reference/delete-connected-organization.md): Deletes a connected organization and revokes the associated OAuth connection. The underlying Tremendous organization is not affected and remains accessible. - [Connected organization members](https://developers.tremendous.com/reference/connected-organization-members.md) - [Connected organization member schema](https://developers.tremendous.com/reference/obj-schema-connected-organization-members.md) - [List connected organization members](https://developers.tremendous.com/reference/list-connected-organization-members.md): Retrieve a list of connected organization members. - [Create connected organization member](https://developers.tremendous.com/reference/create-connected-organization-member.md): Create a connected organization member. - [Retrieve a connected organization member](https://developers.tremendous.com/reference/get-connected-organization-member.md): Retrieve the connected organization member, identified by the given `id` in the URL - [Create connected organization member session](https://developers.tremendous.com/reference/create-connected-organization-member-session.md): Create a connected organization member session. - [Remove a connected organization member](https://developers.tremendous.com/reference/delete-connected-organization-member.md): Removes a connected organization member. If the member has completed registration and has an associated Tremendous member, that membership is also revoked. The connected organization itself is not affected. ## Changelog - [International balance support](https://developers.tremendous.com/changelog/international-balance-support.md) - [Product descriptions](https://developers.tremendous.com/changelog/product-descriptions.md) - [Added: expires_at field in Reward schema](https://developers.tremendous.com/changelog/added-expires_at-field-in-reward-schema.md) - [Bulgarian Lev (BGN) Transition to Euro (EUR)](https://developers.tremendous.com/changelog/bulgarian-lev-bgn-transition-to-euro-eur.md) - [New webhook event](https://developers.tremendous.com/changelog/new-webhook-event.md)