Introduction

Welcome to the Popdeem API Documentation

The Popdeem API provides a RESTful interface to interact with our rewards, social feeds and user information. Popdeem API Base URL: https://api.popdeem.com/api/v2/

Authentication

To authenticate with the API you must send a valid API key header with each request but registration. All calls that deal with the logged in user will require the user-token.

This token is issued at login, and must be kept in memory until the user's session ends. All requests and responses are in JSON format.

Popdeem uses an Api Key to grant access to the API. Please contact your account manager to obtain your Api Key.

Api-Key

API key's are given to customers after they signed up with Popdeem. This needs to be embedded as a header to all requests they make to the Popdeem API. Api-Key: API-KEY

User-Token

User Token gets assigned after login and used for identification on each request after login. User-Token: USER_TOKEN

User Endpoints

POST /users

cURL Request

Facebook

curl -X POST \
  https://api.popdeem.com/api/v2/users \
  -H 'api-key: API_KEY' \
  -H 'Accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
        "user" : {
          "facebook" : {
            "access_token" : "FACEBOOK_ACCESS_TOKEN",
            "id" : "FACEBOOK_USER_ID"
          },
          "unique_identifier" : "UNIQUE_UUID_INDENTIFIER"
        }
      }'

Twitter

curl -X POST \
  https://api.popdeem.com/api/v2/users \
  -H 'api-key: API_KEY' \
  -H 'Accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
        "user" : {
          "twitter" : {
            "access_token" : "TWITTER_ACCESS_TOKEN",
            "access_secret" : "TWITTER_ACCESS_SECRET",
            "id" : "TWITTER USER_ID"
          },
          "unique_identifier" : "UNIQUE_UUID_INDENTIFIER"
        }

Instagram

curl -X POST \
  https://api.popdeem.com/api/v2/users \
  -H 'api-key: API_KEY' \
  -H 'Accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
        "user" : {
          "instagram" : {
            "access_token" : "INSTAGRAM_ACCESS_TOKEN",
            "id" : "INSTAGRAM_USER_ID"
          },
          "unique_identifier" : "UNIQUE_UUID_INDENTIFIER"
        }'

Sample JSON Response

 {
  "user": {
    "facebook": {
      "id": 100008254122068,
      "access_token": "CAAEgheFwHncBAFpQBNCHUZAdLpD7odJLgQriqcdcxt0OFghQNxJ8xmKD8g9C8Udjgds2oUEzXVzu1l90MZCkZCZAukjEyY2pP4wZDZD",
      "expiration_time": "21410359746"
    },
    "twitter": {
      // TBD
    },
      "instagram": {
      // TBD
    },
    "profile_picture_url": "http://example.com/asdf.png",
    "first_name": "John",
    "last_name": "Doe",
    "sex": "male",
    "hypescore": {
      "value": 45678,
      "adjust": {
        "value": 45678,
        "min": 0,
        "max": 100
      }
    },
    "type": "general",
    "id": 123,
    "user_token": "S3criTt0k3n!"
  }
}

Creates & registers a Popdeem user with associated social credentials

HTTP Method:	Endpoint:
POST	https://api.popdeem.com/api/v2/users

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY

Parameter	Description	Optional
facebook		true
id	Facebook ID used to post content.	false
access_token	Facebook Access Token for authentication purposes	false
twitter		true
id	Twitter ID used to post content.	false
access_token	Twitter Access Token for authentication purposes.	false
access_secret	Twitter Access Secret for authentication purposes.	false
instagram		true
id	Instagram ID used to post content.	false
access_token	Instagram Access Token for authentication purposes	false

GET /users

cURL Request

curl -X GET \
    https://api.popdeem.com/api/v2/users/123 \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H "Api-Key: API_KEY" \
     -H "User-Token: USER_TOKEN" \

Sample JSON Response

 {
  "user": {
    "facebook": {
      "id": 100008254122068,
      "tester": "false"
      "access_token": "CAAEgheFwHncBAFpQBNCHUZAdLpD7odJLgQriqcdcxt0OFghQNxJ8xrrcmKD8g9C8Udjgds2oUEzXVzu1l90MZCkZCZAukjEyY2pP4wZDZD",
      "expiration_time": "21410359746"
    },
    "twitter": {
      // TBD
    },
    "profile_picture_url": "http://example.com/profile_image.png",
    "first_name": "John",
    "last_name": "Doe",
    "sex": "male",
    "hypescore": {
      "value": 45678,
      "adjust": {
        "value": 45678,
        "min": 0,
        "max": 100
      }
    },
    "type": "general",
    "id": 123,
    "user_token": "S3criTt0k3n!"
  }
}

Returns the user information for the ID included in the request.

HTTP Method:	Endpoint:
GET	https://api.popdeem.com/api/v2/users/USER_ID

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN

PUT /users

cURL Request

curl -X PUT \
    https://api.popdeem.com/api/v2/users/123 \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H "Api-Key: API_KEY" \
     -H "User-Token: USER_TOKEN" \
     -d "platform=ios" \
     -d "device_token=11111111" \
     -d "latitude=13.1111" \
     -d "longitude=52.134422"

Sample JSON Response

{
  "user": {
    "facebook": {
      "id": 100008254122068,
      "tester": "false"
      "access_token": "CAAEgheFwHncBAFpQBNCHUZAdLpD7odJLgQriqcdcxt0OFghQNxJ8xEvCssJXqqV70rlumXErrcmKD8g9C8Udjgds2oUEzXVzu1l90MZCkZCZAukjEyY2pP4wZDZD",
      "expiration_time": "21410359746"
    },
    "twitter": {
      // TBD
    },
    "profile_picture_url": "http://example.com/asdf.png",
    "first_name": "John",
    "last_name": "Doe",
    "sex": "male",
    "hypescore": {
      "value": 45678,
      "adjust": {
        "value": 45678,
        "min": 0,
        "max": 100
      }
    },
    "type": "general",
    "id": 123,
    "user_token": "S3criTt0k3n!"
  }
}

Updates the existing user record with additional data.

This is used to keep track of the first location that a user signed up with. If theres not already a latitude and longitude for the given user we'll save it.

We also use this to store a users third_party_user_token if required

HTTP Method:	Endpoint:
PUT	https://api.popdeem.com/api/v2/users/USER_ID

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN

POST /connect_social_account

cURL Request

curl -X POST \
   https://api.popdeem.com/api/v2/users/connect_social_account \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H "Api-Key: API_KEY" \
    -d "user[twitter][id]=2798595542" \
    -d "user[twitter][access_token]=2798595542-kh65faManTNs0MIG6V4UYTzByPIyUo6cwcY6LFl" \
    -d "user[twitter][acess_secret]=7RVn43WPHgzmGPFdUeh6OXa1uvULj8NiRPnZys7tptLwA"\

Sample JSON Response

{
    "user": {
      "facebook": {
        "id": 100008254122068,
        "tester": "false"
        "access_token": "CAAEgheFwHncBAFpQBNCHUZAdLpD7odJLgQriqcdcxt0OFghQNxJ8xEvCsssJLhG23jppnSK476pvBErrcmKD8g9C8Udjgds2oUEzXVzu1l90MZCkZCZAukjEyY2pP4wZDZD",
        "expiration_time": "21410359746"
      },
      "twitter": {
        "id": 2798595542,
        "tester": "false",
        "access_token": "2798595542-kh65faManTNs0MIG6V4UYTzByPIyUo6cwcY6LFl",
        "access_secret": "7RVn43WPHgzmGPFdUeh6OXa1uvULj8NiRPnZys7tptLwA"
      },
      "profile_picture_url": "http://example.com/asdf.png",
      "first_name": "John",
      "last_name": "Doe",
      "sex": "male",
      "hypescore": {
        "value": 45678,
        "adjust": {
          "value": 45678,
          "min": 0,
          "max": 100
        }
      },
      "type": "general",
      "id": 123,
      "user_token": "S3criTt0k3n!"
    }
  }
}

Connects an a new social media account to the existing user record

HTTP Method:	Endpoint:
POST	https://api.popdeem.com/api/v2/users/USER_ID

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY

POST /disconnect_social_account

cURL Request

curl -X POST \
    https://api.popdeem.com/api/v2/users/disconnect_social_account \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H "Api-Key: API_KEY" \
    -d "user[twitter][id]=2798595542" \
    -d "user[twitter][access_token]=2798595542-kh65faManTNs0MIG6V4UYTzByPIyUo6cwcY6LFl" \
    -d "user[twitter][acess_secret]=7RVn43WPHgzmGPFdUeh6OXa1uvULj8NiRPnZys7tptLwA"\

Sample JSON Response

{
  "user": {
      "facebook": {
        "id": 100008254122068,
        "tester": "false"
        "access_token": "CAAEgheFwHncBAFpQBNCHUZAdLpD7odJLgQriqcdcxt0OFghQNxJ8x89ZAx7XodxMF0Jl4dKpvBErrcmKD8g9C8Udjgds2oUEzXVzu1l90MZCkZCZAukjEyY2pP4wZDZD",
        "expiration_time": "21410359746"
      },
      "profile_picture_url": "http://example.com/profile_image.png",
      "first_name": "John",
      "last_name": "Doe",
      "sex": "male",
      "hypescore": {
        "value": 45678,
        "adjust": {
          "value": 45678,
          "min": 0,
          "max": 100
        }
      },
      "type": "general",
      "id": 123,
      "user_token": "S3criTt0k3n!"
    }
  }
}

Discconects social media account from the existing user record

HTTP Method:	Endpoint:
POST	https://api.popdeem.com/api/v2/users/USER_ID

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY

POST /init_non_social_user

cURL Request

curl -X POST \
  http://api.popdeem.com/v2/users/init_non_social_user \
  -H 'Api-Key: API_KEY' \
  -H 'User-Token: USER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
        "user" : {
          "platform" : "ios",
          "device_token" : "<xxxx-xxxx-xxxx-xxxx>",
          "unique_identifier" : "UNIQUE_IDENTIFIER"
        }
      }'

In order to track user conversion, it is necessary to register a non social user when Popdeem is added to your platform. When this user registers, the Non Social User is converted to a Social User. This should be done only once per user.

HTTP Method:	Endpoint:
POST	https://api.popdeem.com/api/v2/users/init_non_social_user

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN

Parameter	Description	Required
device_token	Token used to send push notifications for the device. Popdeem uses push notifications unique_identifier	false
platform	Holds the information about the device used by current user. Values can be web, ios or android.	true

Rewards Endpoints

GET /rewards

cURL Request

curl -X GET \
    https://api.popdeem.com/api/v2/rewards \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H "Api-Key: API_KEY" \
     -H "User-Token: USER_TOKEN" \

Sample JSON Response

 {
  "rewards": [
    {
      "id": 11045,
      "rules": "Lorem ipsum",
      "status": "",
      "reward_type": "sweepstake",
      "picture": "http://asdf.com/asdf.png",
      "cover_image": "http://asdf.com/cover.png",
      "created_at": 987654321,
      "available_until": 087654323456,
      "brand": {
        "priority": 1,
        "opening_time": "",
        "id": 1243,
        "name": "Brand",
        "logo": "http://asdf.com/logo.png",
        "contacts": {
          "phone": "087654321",
          "email": "joe@brand.com",
          "web": "http://brand.com",
          "facebook": "http://facebook.com/brand",
          "twitter": "http://twitter.com/brand"
        },
        "locations": [
          {
            "id": "456",
            "latitude": "123.23",
            "longitude": "-0.234",
            "address": "123 Broad Street, Dublin, Ireland",
            "facebook_id": "8765rfghjkl"
          },
        ],
        "location_verification": "true"
      }
    },
  ]
}

Returns a list of social rewards available to the current user.

HTTP Method:	Endpoint:
GET	https://api.popdeem.com/api/v2/rewards

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN

POST /claim_discovered

cURL Request

Facebook

curl -X POST \
  https://api.popdeem.com/api/v2/rewards/11045/claim_discovered \
  -H 'Api-Key: API_KEY' \
  -H 'User-Token: USER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
        "message" : "Claim Message",
        "file" : "image_file_png_representation",
        "facebook" : {
          "access_token" : "facebook_access_token",
          "id" : "facebook_id",
        }
      }'

Twitter

curl -X POST \
  https://api.popdeem.com/api/v2/rewards/11045/claim_discovered \
  -H 'Api-Key: API_KEY' \
  -H 'User-Token: USER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
        "message" : "Claim Message",
        "file" : "image_file_png_representation",
        "twitter" : {
          "access_token" : "twitter_access_token",
          "access_secret" : "twitter_access_secret"
        }
      }'

Instagram

curl -X POST \
  https://api.popdeem.com/api/v2/rewards/11045/claim_discovered \
  -H 'Api-Key: API_KEY' \
  -H 'User-Token: USER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
        "message" : "Claim Message",
        "file" : "image_file_png_representation",
        "instagram" : {
          "access_token" : "instagram_access_token"
        }
      }'

curl -X POST \
  https://api.popdeem.com/api/v2/rewards/11045/claim_discovered \
  -H 'Api-Key: API_KEY' \
  -H 'User-Token: USER_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
        "message" : "Claim Message",
        "file" : "image_file_png_representation",
        "instagram" : {
          "access_token" : "instagram_access_token"
        }
      }'

Sample JSON Response

 {
  "reward": {
    "id": 11045,
    "rules": "Lorem ipsum",
    "status": "",
    "reward_type": "sweepstake",
    "picture": "http://asdf.com/asdf.png",
    "cover_image": "http://asdf.com/cover.png",
    "created_at": 987654321,
    "available_until": "087654323456",
    "brand": {
      "priority": 1,
      "opening_time": "",
      "id": 1243,
      "name": "Brand",
      "logo": "http://asdf.com/logo.png",
      "contacts": {
        "phone": "087654321",
        "email": "joe@brand.com",
        "web": "http://brand.com",
        "facebook": "http://facebook.com/brand",
        "twitter": "http://twitter.com/brand"
      },
      "locations": [
        {
          "id": "456",
          "latitude": "123.23",
          "longitude": "-0.234",
          "address": "123 Broad Street, Dublin, Ireland",
          "facebook_id": "8765rfghjkl"
        }
      ],
      "location_verification": "true"
    }
  }
}

Claims the reward (REWARD_ID = 11045) for the current user.

HTTP Method:	Endpoint:
POST	https://api.popdeem.com/api/v2/rewards/REWARD_ID/claim_discovered

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN

POST /redeem

cURL Request

curl -X POST \
    https://api.popdeem.com/api/v2/rewards/11045/redeem \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H "Api-Key: API_KEY" \
     -H "User-Token: USER_TOKEN" \

Sample JSON Response

 {
  "reward": {
    "id": 123,
    "type": "sweepstake",
    "status": "available",
    "request": {
      "id": 234,
      "expired_at": 987654435
    }
  }
}

Redeems the reward (REWARD_ID = 11045) for the current user.

HTTP Method:	Endpoint:
POST	https://api.popdeem.com/api/v2/rewards/REWARD_ID/redeem

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN

POST /autodiscovery

cURL Request

curl -X POST \
    https://api.popdeem.com/api/v2/rewards/11045/autodiscovery \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H "Api-Key: API_KEY" \
     -H "User-Token: USER_TOKEN" \
     -d "network=facebook"\

Sample JSON Response

{
    "validated": true,
    "text": "#test",
    "media_url": "https://scontent.xx.fbcdn.net/v/t1.0-9/s720x720/58003963_10161567679445287_8622199923925843968_n.jpg",
    "post_key": "10156869179450287_10161567679840287",
    "network": "facebook",
    "profile_picture_url": "https://s3-eu-west-1.amazonaws.com/profile-photo.png",
    "social_name": "Daniel Farrell"
}

Scans the users social network to verify they have made the neccessary post to claim a reward

HTTP Method:	Endpoint:
POST	https://api.popdeem.com/api/v2/rewards/REWARD_ID/autodiscovery

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN

Params
network	facebook
network	twitter
network	instagram

Wallet Endpoints

GET /wallet

cURL Request

curl -X GET \
    https://api.popdeem.com/api/v2/rewards/wallet \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H "Api-Key: API_KEY" \
     -H "User-Token: USER_TOKEN" \

Sample JSON Response

{
  "rewards": [
    {
      "id": 123,
      "rules": "Lorem ipsum",
      "status": "",
      "reward_type": "sweepstake",
      "picture": "http://asdf.com/asdf.png",
      "cover_image": "http://asdf.com/cover.png",
      "created_at": 987654321,
      "available_until": 087654323456,
      "brand": {
        "priority": 1,
        "opening_time": "",
        "id": 1243,
        "name": "Brand",
        "logo": "http://asdf.com/logo.png",
        "contacts": {
          "phone": "087654321",
          "email": "joe@brand.com",
          "web": "http://brand.com",
          "facebook": "http://facebook.com/brand",
          "twitter": "http://twitter.com/brand"
        },
        "locations": [
          {
            "id": "456",
            "latitude": "123.23",
            "longitude": "-0.234",
            "address": "123 Broad Street, Dublin, Ireland",
            "facebook_id": "8765rfghjkl"
          },
        ],
        "location_verification": "true"
      }
    },
  ]
}

Returns a list of rewards that has been claimed but not redeemed yet.

HTTP Method:	Endpoint:
GET	https://api.popdeem.com/api/v2/wallet

Headers
Api-Key	API_KEY
User-Token	USER_TOKEN
Content-Type	application/json
Accepts	application/json

Activity Feed Endpoints

GET /feeds

cURL Request

curl -X GET \
    https://api.popdeem.com/api/v2/feeds \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H "Api-Key: API_KEY" \

Sample JSON Response

{
"feeds": [
    {
        "id": 170055,
        "brand": {
            "name": "Popdeem Customer",
            "logo": "logo.png"
        },
        "reward": {
            "type": {
                "id": 11041,
                "name": "coupon",
                "desc": "Reward your customers instantly for sharing their experiences. ",
                "created_at": "2014-09-26T11:37:17.000Z",
                "updated_at": "2014-09-26T11:37:17.000Z"
            },
            "description": "Social Reward"
              },
        "time_ago": "1 week ago",
        "created_at": "1548081085",
        "likes": 103,
        "comments": 12,
        "hashtag": "#socialrewards",
        "network": "facebook",
        "influencer_score": 64,
        "advocacy_score": 81,
        "picture=": "https://s3-eu-west-1.amazonaws.com/activity-feed-photo.png",
        "picture": "https://s3-eu-west-1.amazonaws.com/activity-feed-photo.png",
        "caption": "Best coffee here! #socialrewards",
        "social_account": {
            "user": {
                "id": 59501,
                "first_name": "Daniel",
                "last_name": "Farrell"
            },
            "profile_picture": "https://s3-eu-west-1.amazonaws.com/profile-photo.png"
        }
    }

Returns a list of images, captions & user information to be included in the Popdeem user activity feed.

HTTP Method:	Endpoint:
GET	https://api.popdeem.com/api/v2/feeds

Headers
Api-Key	API_KEY
Content-Type	application/json
Accepts	application/json

Custom Feed Parameters		Examples
min_likes	int	100
min_comments	int	10
reward_id	int	11041
hashtag	string	popdeem
network	string	facebook
min_influencer_score	int	60
min_advocacy_score	int	70
start_date	DateTime	YYYY-MM-DD
end_date	DateTime	YYYY-MM-DD

GET /feeds/partner

cURL Request

curl -X GET \
    https://api.popdeem.com/api/v2/feeds/partner \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H "Api-Key: API_KEY" \

Sample JSON Response

{
   "feeds": [
       {
           "id": 170055,
           "brand": {
               "name": "Customer 1",
               "logo": "logo.png"
           },
           "reward": {
               "type": {
                   "id": 3,
                   "name": "credit",
                   "amount". "$1"
                   "desc": "Reward your customers instantly for sharing their experiences. ",
                   "created_at": "2014-09-26T11:37:17.000Z",
                   "updated_at": "2014-09-26T11:37:17.000Z"
               },
               "description": "Social Reward"
                "action type": "photo"
                "social media".: "instagram"
           },
           "time_ago": "3 months ago",
           "created_at": "1548081085",
           "picture=": "https://s3-eu-west-1.amazonaws.com/activity-feed-photo.png",
           "picture": "https://s3-eu-west-1.amazonaws.com/activity-feed-photo.png",
           "hashtag": "#socialrewards",
           "social_account": {
               "user": {
                   "id": 59501,
                   "first_name": "Daniel",
                   "last_name": "Farrell"
                   "third_party_token": "daniel.farrell@popdeem.com"
               },
               "profile_picture": "https://s3-eu-west-1.amazonaws.com/profile-photo.png"
           }
       }

Returns a custom feed for each Popdeem partner. Similar to /feeds, /feeds/partner returns a list of images, captions & user information to allow Popdeem partners to manage their own custom activity feed.

HTTP Method:	Endpoint:
GET	https://api.popdeem.com/api/v2/feed/partner

Headers
Api-Key	API_KEY
Content-Type	application/json
Accepts	application/json

Messages Endpoints

GET /messages

cURL Request

curl -X GET \
  http://api.popdeem.com/v2/messages \
  -H 'Accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Api-Key: API_KEY' \
  -H 'User-Token: USER_TOKEN' \

Sample JSON Response

{
    "messages": [
        {
            "id": 68437,
            "brand_id": null,
            "reward_id": null,
            "title": "Notification Title",
            "body": "Notification Body",
            "image_url": "https://s3-eu-west-1.amazonaws.com/popdeem/customerslogo.jpg",
            "read": false,
            "created_at": 1554306031,
            "sender_name": "Customer Name",
            "sent_time": 1554306031
        }
    ]
}

Returns a list messages sent to the user with the USER_TOKEN included in the request.

HTTP Method:	Endpoint:
GET	https://api.popdeem.com/api/v2/messages

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN

POST /mark_as_read

cURL Request

curl -X POST \
  http://api.popdeem.com/api/v2/messages/11041/mark_as_read \
  -H 'Accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Api-Key: API_KEY' \
  -H 'User-Token: USER_TOKEN' \

Marks message with MESSAGE_ID = 11041 as read.

HTTP Method:	Endpoint:
POST	http://api.popdeem.com/api/v2/messages/MESSAGE_ID/mark_as_read

Headers
Content-Type	application/json
Accepts	application/json
Api-Key	API_KEY
User-Token	USER_TOKEN