Badges

Request Details

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

Request Query Parameters

Field Name Sample Value Required Format Description
page 1 No Integer

Clients can send a 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.

Response

Field Name Sample Value Required Format Description
paging See Response - PAGING Object. Yes Object Pagination of the API response.
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 – 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.
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.
is_enabled 1 Yes Boolean If the badge is enabled.
badge_states See BADGE STATES OBJECT. Yes Object Details the available badge states.
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.
segment See SEGMENT OBJECT. Yes Object Linked segment or segment group.
BADGE STATES OBJECT
state earned Yes String State (unearned, in progress, earned).
order 1 Yes Integer Order of badge status state.
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.
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.
SEGMENT OBJECT
name Canada Members No String Name of the linked segment.
subscription_id 1043 No Integer ID of the mapped segment.
eligibility_type inclusion No String Inclusion or exclusion.

Sample Response

{ "paging": { "total": 100, "pages": 10, "next_page": "https://api[client_id].crowdtwist.com/v2.1/badges?page=2&page_size=15&api_key=", "prev_page": "https://api[client_id].crowdtwist.com/v2.1/badges?page=4&page_size=15&api_key=" }, "badges": [ { "id": "123456", "name": "badge_001", "title": "Game Attendance", "badge_states ": [ { "state": "unearned", "order": 1, "description": "Attend a game to show your fanage", "image_url": "http://www.imagestorage.com/image" }, { "state": "earned", "order": 2, "description": "You attended a game, way to go!", "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", "is_enabled": 1, "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 } ], "badge_extra_data": { "customer_variable": "customer data" }, "segment": [ { "name": "Canada Members", "subscription_id": 1043, "eligibility_type": "inclusion" } ] } ] }