User Badges

Request Details

Item Value
Description Returns the details of badges available within a program for a specific user.
Method GET
Endpoint https://[environment]api[client_id].crowdtwist.com/v2.1/users/[user_id]/badges? page=[page_number]&page_size=[page_size]&api_key=[api_key]&id_type=[id_type]

Request Query Parameters

Field Name Sample Value Required Format Description
page 1 No Integer

Clients can send the request for a specific page number.

  • If no page number is requested, we return the first page.

  • If page requested is not a valid value, we return the first page.

  • If page is out of range (for example, if the page number is 0 or less), we return an empty rewards array and next page has a link to page 1. If page number exceeds the length of pages available, we return an empty rewards array and return a link to the previously available page.
page_size 15 No Integer Size of the page returned in the response (max of 25). If no page_size is specified, we default with 10 badges in the response.
api_key QWERTYP Yes String

Client-configured API key.
user_id user@crowdtwist.com Yes String ID of the user.
id_type Email No String

Type of ID being sent:

  • email

  • facebook_user_id

  • twitter_user_id

  • id (CrowdTwist ID) – default ID if id_type is not specified

  • third_party_id

  • username

  • mobile_phone_number

Response

Field Name Sample Value Required Format Description
paging See Response - PAGING Object. Yes Object Pagination of the API response.
user_counts See Response - USER COUNTS Object. Yes Object Counts of member badges.
badges See Response - BADGES Object. Yes Object Badges.


Response – PAGING Object

Field Name

Sample Value

Required

Format

Description

total

100

Yes

Integer

The total number of badges.

pages

50

Yes

Integer

The total page numbers.
next_page HTTPS:// API[CLIENT_ID].CROWDTWIST.COM/V2.1/ BADGES?PAGE=1&API_KEY=[API_KEY] No String The URL of the next page.
prev_page   No String The URL of the previous page.


Response – USER COUNTS Object

Field Name

Sample Value

Required

Format

Description

earned_lifetime

50

Yes

Integer

Number badges earned by the member regardless of badge state.

earned_unique

1

Yes

Integer

Number of unique badges the member has earned.
earned_total 2 Yes Integer Number of badges the member has earned (inclusive of state).
unearned 1 Yes Integer Number of badges available to the member to earn.


Response – BADGES Object

Field Name

Sample Value

Required

Format

Description

id

456

Yes

Integer

Unique identifier of the badge.

name

badge_001

Yes

String

Internal unique name of the badge.
title Game Attendance Yes String Public name of the badge.
state EARNED Yes String The state of the badge for the member.
description You attended a game, way to go! No String Public description of the state.
image_url http://www.imagestorage.com/image No String URL of the badge state image.
date_start 2019-01-01T00:00:00.000Z Yes Date (ISO-8601) Date on which the badge earn starts.
date_end   No Date (ISO-8601) Date on which the badge earn ends.
display_date_start 2019-01-01T00:00:00.000Z Yes Date (ISO-8601) Date on which the badge starts being displayed to a member.
display_date_end   No Date (ISO-8601) Date on which the badge stops being displayed to a member.
badge_extra_data   Yes JSON array Extra key-value pairs at the badge level configuration.
earn_count 2 Yes Integer Number of times the member has earned the badge.
frequency See FREQUENCY OBJECT. Yes Object Details the frequency at which a member can earn the badge.
tags See TAGS OBJECT. Yes Object Tags linked to the badge for organization.
earn_latest See EARN LATEST OBJECT Yes Object Details of the 10 most recently earned badges.
FREQUENCY OBJECT
freq_cap 1 No Integer The number of times a member can earn the badge within the freq_period.
freq_period_id 1 No Integer The ID of the freq_period.
freq_period_name Week No String The name of the freq_period.
freq_max 5 No Integer The maximum number of times a member can earn the page.
TAGS OBJECT
tag_name Game No String Name of the linked tag.
tag_id 1 No Integer ID of the linked tag.
badge_extra_data   Yes JSON array Extra Data configured at the badge level.
EARN LATEST OBJECT
earn_id 345 No Integer Unique ID of the badge earned.
date_earned 2019-01-02T00:00:00.000Z No Date (ISO-8601) Date the badge was earned.
date_created 2019-01-02T01:00:00.000Z No Date (ISO-8601) Date the earned badge was processed.
custom_data   No JSON array Client-provided custom data unique to the earned badge.

Sample Response

{ "paging":{ "total":100, "pages":10, "next_page":"https://api[client_id].crowtwist.com/v2.1/users/[user_id]/badges?page=2&page_size=15&api_key=", "prev_page":"https://api[client_id].crowdtwist.com/v2.1/users/[user_id]/badges?page=4&page_size=15&api_key=" }, "user_counts":{ "earned_lifetime":50, "earned_unique":1, "earned_total":2, "unearned":1 }, "badges":[ { "id":"123456", "name":"badge_001", "title":"First Login", "description":"Awarded for logging in for the first time.", "image_url": "http://www.imagestorage.com/image", "date_start":"2019-05-03T19:01:23.000Z", "date_end":"2019-05-03T19:01:23.000Z", "display_date_start":"2019-05-03T19:01:23.000Z", "display_date_end":"2019-05-03T19:01:23.000Z", "frequency": { "freq_cap":1, "freq_period_id":1, "freq_period_name":"week", "freq_max":5 }, "tags":[ { "tag_name":"Football", "tag_id":1 }, { "tag_name":"Cricket", "tag_id":2 } ], "earn_count":2, "earn_latest": { "earn_id": 345, "date_earned":"2019-05-03T19:01:23.000Z", "date_created":"2019-05-03T19:01:23.000Z", "custom_data":{"customer_variable":"customer data"} }, "badge_extra_data":{ "customer_variable":"customer data" } }, ...... next badge ] }