Marketing API

The Marketing API provides access to marketing content created using the Uplyft Platform.

Introduction

This document was written for product managers and developers as an integration guide for the Uplyft Marketing API.

Our mission is to make integrating Uplyft as easy as possible for you. Please feel free to contact us for further questions and feedback on this setup guide via support@uplyft.com.‚Äč

Uplyft Marketing API uses graph query language (GraphQL) to expose Campaign and Business Account information for applications through programatic access. Responses are in JSON format.

For an introduction to GraphQL, see the official web site graphql.org.

A Business Account represents a company, a store, a merchant, etc. and contains things like logo and name. A Campaign is a piece of advertising information that can be used to communicate to customers and contains image, title, etc..

The testing environment is accessible at https://marketing-api.alpha.uplyft.com.

The production environment is accessible at https://marketing-api.uplyft.com.

Client authentication

In order to access the API you will need an API Key which will be provided by Uplyft. Once an API Key was supplied, you can start sending requests. We suggest using one of the client libraries in this list: https://graphql.org/code/#graphql-clients.

The request has to contain the API Key in the x-api-key HTTP header.

Curl example:

$ curl -d "{\"query\": \"query {businessAccounts { items { name } }}\" }" -H "x-api-key: da2-bm72k7ovvjayvfj7ypdmx5fs4y" -XPOST https://marketing-api.alpha.uplyft.com

Querying for campaigns

If you need to, for example, fetch the campaigns of a certain business account you would make a request with the following GraphQL query:

query {
campaigns(filter: {businessAccountId: {eq: "57111bcda5ab7b94cb1990e1"}}, limit: 1) {
items {
id
content {
title
subtitle
description
featuredImage(width: 800) {
url
}
}
}
nextToken
}
}

The limit argument specifies the number of items to return. In this example, the limit argument is on purpose set to 1 in order to illustrate the usage of nextToken property for pagination.

Response:

{
"data": {
"campaigns": {
"items": [
{
"id": "d451df3f-ba52-45f4-895c-742d3eacb0ea",
"content": {
"title": "Subscription campaign",
"subtitle": "Subscribe to win!",
"description": "Subscribe to our newsletter and win many prizes!",
"featuredImage": {
"url": "https://d2o0nbdtwvhrj9.cloudfront.net/fanmiles/image/upload/w_800/chl9qzrzmwbzpi2vzp1h"
}
}
}
],
"nextToken": "eyJ2ZXJzaW9uIjoyLCJ0b2tlbiI6IkFRSUNBSGdtYVZObHlaR3FSa3hDRnFVWWdFeEZDM0FMY1JRdE9UOEt2dWFLMExzcjJ3SGVMWEtLY1E3bDUxd0g2Mk5XdjFGb0FBQURUVENDQTBrR0NTcUdTSWIzRFFFSEJxQ0NBem93Z2dNMkFnRUFNSUlETHdZSktvWklodmNOQVFjQk1CNEdDV0NHU0FGbEF3UUJMakFSQkF5ekZhRFI4d0svWi9HcDAyVUNBUkNBZ2dNQXRSK0tXM1VFQTV6SmJBSHA1NWM1cnVpQldWd3JyZWFldWpiUDlvUmE4eTRwRVVHNDNJeTlUdWVVb0pXZUhNMGQvdFJuWkt2dlk4N0JhMFprYm43cWRXTENsN0JkS00wL1RSVitHdERDOTlxZlVlMytuMEQraHk1Q2ljcnQvSWtDZlkwT09BODg0Z21jZDZ6dW5vNWYxNFRUUUg0SmxYa3hPeTI1cjlhc0pvcFd3anN1TldZSzlkN0s5cWQrVmNSY3V2bGE3cFRZNHJQZnArSDF2M2tHNmpGaWRhWE0rQXk2S3NSc0tKTFYrNGEvdlFRMzYyQUtnRDg2Z29TUENjYmM0Z2hHaFJwSk40SXErMjJJSWozbTVpeFZrUWhRRkFzbStGTXFDbFVNeDdCWEtYNFZvMmNoTWgyckllQjZIandLLzFwd1RiVFJiYldQRWI4YmJtZVpSejd1NmRPTy91THRpdUpvZEt6S1NrQTNwZlR5K05RTEI0MXVCNWJTYWtkVDNBTkxpSU1XUkYzTWVvZkgxWnlFZUlWZVBmTVFKcmhXNzd6bElKeXVER0pqVkNDTVFkeXhEa0JMeG9ENmZWN3hramZxWk1PZTBYOWhlWExzZTNhR1dPOHZrdER6ZEZYRWFTeG1Ed0U4K2h0dk1DaEd6aCtDU3poN2h4dmtWL0Y1Ri9ibkY1NVR5dTVaaGcwdHRrSCtXa1NWbzBPcjJlK3kzeHVPK1BVUTRicEM1cWxCU1QzVDJoU0xiQkxxVUM5NlhiV1VOZzhpMnVvUzB5dE1JemZaVmdaNzN1WHNoTkgvcVVURmI1T08xc2dlZnpkbmV3QXVMOGwwSVlSd0NqZW1EeFdIejhXNzQvd0RBZXppQTUwbG56ZFJXVUIvZHladGFNZis5SERDTE83OXpxYllWTFRGaEk4T1FUR3Z4b2c4SENxM2RGUWFMRU9MeklQckkySCtnSzI2UFcvNEJzOVovUk1tWE9YdG4wM2xHRDFncHg3OXIwc0JTY0o1RFFZTnhUTDQwdkwvd05Ya0VycVJrTHhuTjlOZXkrOUdyWWRhNkpGRmlKL2k0NUpKSFJEVkVqTUhjU2hVMEs3VWh3N1RKRWgwbmtVYUR6eURURW5OQVczcjM2d0YwV3VGK0h0Q3J5ejE1OXBXRDhDdURUei9VbGlKeFRmdFkrQ2xCMEJqbFVMVFFZb0tOV3JmUDJLdWVCOE1Za1ZUTldzVUtFZDQyZGhINGlIODZwaGhoMUhhRUFpOEVaQ0tBcXJIanF2c0ZmTW5jeU10VlJTMWZMakIzWERSb1ZmZkY1eThEVkhrNS9WNTRFTWlkcExibGFqR21OMkc4MTVCQSt1d0gwSnoifQ=="
}
}
}

Querying for a single campaign

Retrieve one campaign with a specified ID.

query {
campaign(id: "d451df3f-ba52-45f4-895c-742d3eacb0ea") {
id
content {
title
subtitle
description
featuredImage(width: 800) {
url
}
}
}
}

Response:

{
"data": {
"campaign": {
"id": "d451df3f-ba52-45f4-895c-742d3eacb0ea",
"content": {
"title": "Subscription campaign",
"subtitle": "Subscribe to win!",
"description": "Subscribe to our newsletter and win many prizes!",
"featuredImage": {
"url": "https://d2o0nbdtwvhrj9.cloudfront.net/fanmiles/image/upload/w_800/chl9qzrzmwbzpi2vzp1h"
}
}
}
}
}

Coupon campaign

query {
campaign(id: "d451df3f-ba52-45f4-895c-742d3eacb0ea") {
id
content {
title
objective {
... on CouponObjective{
price
}
}
}
}
}

Querying Business Accounts

Query to retrieve multiple Business Accounts.

The field pending indicates whether the business account has been approved by the program manager. If pending is false, it typically means that it should not be displayed to end-users.

The field customProperties are arbitrary fields specific to a certain program. In this example it is used to store a Stripe User Id that can be used to process payments.

query {
businessAccounts {
items {
name
websiteUrl
address {
streetAddress
postalCode
city
}
description
phoneNumber
category
logo {
url
}
pending
customProperties {
key
value
}
}
}
}

Response:

{
"data": {
"businessAccounts": {
"items": [
{
"name": "WASD",
"websiteUrl": "https://www.WASDKeyboards.de",
"address": {
"streetAddress": "Clickity Street 123",
"postalCode": "QW 123",
"city": "Berlin"
},
"description": "The best boards with the best keys. All of them WASD.",
"phoneNumber": "555123456",
"category": "Computer peripherals",
"logo": {
"url": "https://d2o0nbdtwvhrj9.cloudfront.net/fanmiles/image/upload/w_800/chl9qzrzmwbzpi2vzp1h"
},
pending: false,
"customProperties": [
{ "key": "stripeUserId", "value": "acct_1234567" }
]
}
]
}
}
}

Getting coupons

Retrieves one coupon for the associated campaign. Each call returns a new coupon.

mutation {
requestCoupon(campaignId: "d451df3f-ba52-45f4-895c-742d3eacb0ea") {
coupon {
code
}
}
}