Badges Widget
Request Details
| ITEM
|
VALUE
|
| Description
|
Returns the configured badge list for a widget and loyalty member. Localized widget and badge text is returned when a locale is supplied. |
| Method
|
GET |
| Endpoint
|
https://[environment]api[client_id].crowdtwist.com/v2/widgets/badge/[widget_id]/[user_id]?api_key=[api_key]&id_type=[id_type]&__locale__=[language] |
| Content Type
|
application/json |
Host and Path Parameters
| PARAMETER
|
LOCATION / TYPE
|
REQUIRED
|
DESCRIPTION
|
| environment |
host / string |
Yes |
Environment prefix used to construct the client-specific CrowdTwist API host. Deployment-specific value. |
| client_id |
host / string |
Yes |
Client identifier embedded in the CrowdTwist API host name. Deployment-specific value. |
| widget_id |
path / integer |
Yes |
Identifier of the badge widget to retrieve. |
| user_id |
path / string |
Yes |
Identifier for the loyalty member whose badges are returned. |
Request Query Parameters
| PARAMETER
|
LOCATION / TYPE
|
REQUIRED
|
DESCRIPTION
|
| api_key |
query / string |
Yes |
API key used for client identification and authentication. Treat as a secret and transmit only over HTTPS. |
| id_type |
query / string |
Yes |
Identifies how user_id is interpreted. See ID Type Values. |
| __locale__ |
query / string |
No |
Locale used to translate header_text, title, description, and category_name. |
id_type Values
| VALUE
|
DESCRIPTION
|
| id |
CrowdTwist member identifier. |
| email |
Member email address. |
| third_party_id |
External identifier associated with the member. |
| username |
Member username. |
| mobile_phone_number |
Member mobile phone number. |
Response Body
Top-Level Object
| FIELD
|
TYPE
|
SAMPLE VALUE
|
DESCRIPTION
|
| details |
object |
{ "widget_name": "Badge List", ... } |
Presentation metadata for the widget. |
| items |
array |
[ { "id": 1, ... } ] |
Ordered collection of badges returned for the member. |
details
| FIELD
|
TYPE
|
SAMPLE VALUE
|
DESCRIPTION
|
| widget_name |
string |
Badge List |
Widget name (internal). |
| header_text |
string |
lista de insignias |
Translated header text displayed by the widget. |
items
Each array element represents a badge. The array is ordered using sort_order.
| FIELD
|
TYPE
|
SAMPLE VALUE
|
DESCRIPTION
|
| sort_order |
integer |
1 |
Display order of the badge within the widget. |
| id |
integer |
1 |
Unique identifier for the badge. |
| name |
string |
Badge 001 |
Badge name. |
| title |
string |
Has ganado una insignia. |
Translated title displayed for the badge. |
| description |
string |
Aquí tienes cómo conseguir la insignia. |
Translated badge description. |
| img_url |
string (URI) |
https://cdn.crowdtwist.com/.../image.png |
URL of the badge image. |
| date_start |
string (ISO 8601 date-time) |
2026-02-06T05:00:00Z |
ISO 8601 date-time at which the badge becomes active. |
| date_end |
string (ISO 8601 date-time) or null |
null |
ISO 8601 date-time at which the badge ends; null when no end date is set. |
| display_date_start |
string (ISO 8601 date-time) |
2026-02-06T05:00:00Z |
ISO 8601 date-time used for the badge display start. |
| display_date_end |
string (ISO 8601 date-time) |
2026-02-06T05:00:00Z |
ISO 8601 date-time used for the badge display end. |
| frequency |
object |
{ "freq_cap": 1, ... } |
Frequency configuration for the badge. |
| tags |
array |
[ { "tag_name": "Football", ... } ] |
Tags assigned to the badge. |
| earn_count |
integer |
2 |
Number of times the member has earned the badge. |
| earn_latest |
object |
{ "earn_id": 345, ... } |
Most recent badge-earn record for the member. |
| badge_extra_data |
object |
{ "customer_variable": "customer data" } |
Additional badge-level data. Schema is customer-defined. |
frequency
| FIELD
|
TYPE
|
SAMPLE VALUE
|
DESCRIPTION
|
| freq_cap |
integer |
1 |
Numerical identifier for the frequency cap. |
| freq_period_id |
integer |
1 |
Identifier of the frequency period. |
| freq_period_name |
string |
week |
Name of the frequency period. |
| freq_max |
integer |
5 |
Maximum frequency of the badge being issued. |
tags
| FIELD
|
TYPE
|
SAMPLE VALUE
|
DESCRIPTION
|
| tag_name |
string |
Football |
Tag name. |
| tag_id |
integer |
1 |
Unique identifier for the tag. |
earn_latest
| FIELD
|
TYPE
|
SAMPLE VALUE
|
DESCRIPTION
|
| earn_id |
integer |
345 |
Unique identifier for the badge-earn record. |
| date_earned |
string (ISO 8601 date-time) |
2019-05-03T19:01:23.000Z |
ISO 8601 date-time when the badge was earned. |
| date_created |
string (ISO 8601 date-time) |
2019-05-03T19:01:23.000Z |
ISO 8601 date-time when the badge-earn record was created. |
| custom_data |
object |
{ "customer_variable": "customer data" } |
Custom data associated with the badge-earn record. Schema is customer-defined. |
Sample Response Body
{
"details": {
"widget_name": "Badge List",
"header_text": "lista de insignias"
},
"items": [
{
"sort_order": 1,
"id": 1,
"name": "Badge 001",
"title": "Has ganado una insignia.",
"description": "Aquí tienes cómo conseguir la insignia.",
"img_url": "https://cdn.crowdtwist.com/img/v2/94cc1c338b0f84efdedacec31ea8da6468e32e9e/w/h/0/image.png",
"date_start": "2026-02-06T05:00:00Z",
"date_end": null,
"display_date_start": "2026-02-06T05:00:00Z",
"display_date_send": "2026-02-06T05:00:00Z",
"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" }
}
]
}