Oracle CrowdTwist

https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop
Admin
Oracle CrowdTwist is a loyalty platform API that enables registration, profile management, points...
Tokens:181,308
Snippets:698
Trust Score:9.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### GET Request for User Purchases

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserPurchaseHistory.html

This sample demonstrates how to retrieve a user's purchase history using a GET request. It includes parameters for filtering by date range and pagination. The response body contains a list of purchases and pagination details.

```http
GET https://pos12.crowdtwist.com/users/332170040/purchases?id_type=id&page=1&date_start=2022-01-01&date_end=2022-01-12
```

--------------------------------

### Batch Activity Credit File Examples

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/BatchActivityCredit.html

Provides various examples of valid batch file content, including standard formats, custom point overrides, and specific identifier usage.

```text
testing@crowdtwist.com|||testusername|126456789
testing2@crowdtwist.com|||testusername2|126456789
```

```text
testing@crowdtwist.com|||testusername|126456789|400
testing2@crowdtwist.com|||testusername2|126456789|550
```

```text
test303@emailaddress.com||||410061376
```

```text
|54064211|||410061376
```

```text
|54064211|||410061376||1551456336
```

--------------------------------

### Get Usable Coupons for a User (API Request)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UsableCoupons.html

This is a sample HTTP GET request to retrieve all usable coupons for a specific user. It requires the user's email and an API key for authentication. The response will be a JSON array of coupon objects.

```http
GET https://api.crowdtwist.com/v2/users/alice@crowdtwist.com/usable_coupons?api_key=QWERTYUIOP&id_type=email
```

--------------------------------

### Example Batch File Name Convention

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/BatchFulfillment.html

This example demonstrates the required naming convention for batch fulfillment files. The convention includes a timestamp, a counter, a client ID, and a client-specific identifier, followed by the .json extension.

```text
YYYYMMDD_<counter>_<client_id>_pos_<client_specific>.json
```

--------------------------------

### GET /v2.1/activities/extended

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Activities-Extended21.html

Retrieves a paginated list of extended activity definitions available in the system.

```APIDOC
## GET /v2.1/activities/extended

### Description
Retrieves a comprehensive list of activities, including metadata such as points, categories, and tier requirements.

### Method
GET

### Endpoint
https://api.crowdtwist.com/v2.1/activities/extended

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your unique API authentication key.
- **page** (integer) - Optional - The page number for paginated results.

### Request Example
curl -X GET "https://api.crowdtwist.com/v2.1/activities/extended?api_key=QWERTYUIOP"

### Response
#### Success Response (200)
- **paging** (object) - Pagination metadata including total count and next/previous page links.
- **activities** (array) - A list of activity objects containing details like id, name, num_points, and category_id.

#### Response Example
{
  "paging": {
    "total": 133,
    "pages": 14
  },
  "activities": [
    {
      "id": "410045996",
      "name": "redeemed a code",
      "num_points": 1000
    }
  ]
}

### Error Handling
- **401 Unauthorized**: Returned when the API key is invalid or missing.

#### Error Response Example
{
  "error": "invalid_auth",
  "message": "Invalid access credentials."
}
```

--------------------------------

### GET /rewards

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserActivities-Extended21.html

Retrieves a paginated list of rewards and their associated activities.

```APIDOC
## GET /rewards

### Description
Retrieves a list of rewards and activities available within the CrowdTwist platform, including pagination metadata.

### Method
GET

### Endpoint
/v2.1/rewards

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.

### Response
#### Success Response (200)
- **paging** (Object) - Paging information (total, pages, next_page, prev_page).
- **activities** (Array) - List of activity objects.

#### Response Example
{
  "paging": {
    "total": 203,
    "pages": 10,
    "next_page": "http://example.ct.com/v2.1/rewards?page=3",
    "prev_page": "http://example.ct.com/v2.1/rewards?page=1"
  },
  "activities": [
    {
      "id": "1006156",
      "name": "Watched A Video",
      "title": "Ad Hoc Points",
      "description": "Ad Hoc Points",
      "num_points": 2000,
      "image": "http://www.imagestorage.com/image",
      "category_id": "3",
      "category_name": "Interact",
      "type_id": "7",
      "type_name": "Your Site",
      "activity_channel_id": "1",
      "activity_channel_name": "Ad hoc points",
      "freq_cap": "1",
      "freq_period_id": "2",
      "freq_period_name": "One Calendar Day",
      "freq_num_required_attempts": "1",
      "redirect_url": "www.crowdtwist.com",
      "points_on_click": "true"
    }
  ]
}
```

--------------------------------

### Crowdtwist User Custom Data Example

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/PushUserProfile-withTiersv2.html

This example demonstrates how custom data attributes are included in the user data push when they are stored for a user. Instead of 'customData' being null, it contains an object with key-value pairs representing specific user attributes like employee ID and register ID.

```json
"customData":"
  {
    "employee_id": "employee1",
    "register_id": "1",
    "cashier_id": "2"
  }

```

```json
"customData":"
	{
	  "employee_id": "employee1",
	  "register_id": "1",
	  "cashier_id": "2"
	}

```

--------------------------------

### GET /v2.1/activities/extended

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Activities-Extended21.html

Retrieves an enhanced set of activity attribute details with support for pagination.

```APIDOC
## GET /v2.1/activities/extended

### Description
This endpoint returns the enhanced set of activity attribute details. v2.1 of the extended activities endpoint also allows for paginated responses.

### Method
GET

### Endpoint
https://[environment]api[client_id].crowdtwist.com/v2.1/activities/extended

### Parameters
#### Query Parameters
- **api_key** (String) - Required - The API authentication key.
- **page** (Integer) - Optional - The specific page number to retrieve. Defaults to 1.
- **page_size** (Integer) - Optional - The number of entries per page (max 25). Defaults to 10.

### Request Example
GET https://api.crowdtwist.com/v2.1/activities/extended?api_key=QWERTYP&page=1&page_size=10

### Response
#### Success Response (200)
- **activities** (Array) - List of activity objects.
- **links** (Object) - Pagination links for navigation.

#### Response Example
{
  "activities": [],
  "links": {
    "next": "...",
    "previous": "..."
  }
}
```

--------------------------------

### Sample User Creation Request (cURL)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserCreate.html

This sample demonstrates how to create a new user via the CrowdTwist API using a cURL command. It includes essential user details and custom data.

```bash
curl -X POST \
https://api.crowdtwist.com/v2/users?api_key=QWERTYUIOP \
{
  "email_address": "alice@crowdtwist.com",
  "last_name": "Twist",
  "first_name": "Alice",
  "postal_code": "10010",
  "lang_pref":"en",
  "date_of_birth": 344754000,
  "username": "alicetwist",
  "email_is_verified": 1,
  "send_verify_email": 0,
  "sign_up_channel_id": 1,
  "custom_data": {
    "register_id": "1",
    "cashier_id": "2"
  }
}
```

--------------------------------

### Retrieve Survey Results via cURL

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/SurveyResults.html

Example of how to perform a GET request to the survey results endpoint using cURL. Requires a valid survey ID and API key as query parameters.

```bash
curl -X GET 'https://api.crowdtwist.com/v2/survey/23/results?api_key=QWERTYUIOP'
```

--------------------------------

### GET /v2/users/{user_id}/household_invitations

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/HouseholdInviteMemberGet.html

Retrieves a list of household invitations for a specific member.

```APIDOC
## GET /v2/users/[user_id]/household_invitations

### Description
Returns a list of household invitations associated with the specified member.

### Method
GET

### Endpoint
https://[environment]api[client_id].crowdtwist.com/v2/users/[user_id]/household_invitations?api_key=[api_key]

### Parameters
#### Path Parameters
- **user_id** (Integer) - Required - The unique identifier of the member.

#### Query Parameters
- **api_key** (String) - Required - The API key for authentication.

### Response
#### Success Response (200)
- **invitation_id** (Integer) - The id of this invitation.
- **household_id** (Integer) - The id of this household.
- **email_address** (String) - The email address of the invitee.
- **date_sent** (String) - The date this invitation was sent (ISO 8601).
- **status** (String) - The status of this invitation (ACCEPTED, REJECTED, PENDING, REMOVED).

#### Response Example
[
    {
        "invitation_id": 12,
        "household_id": 8,
        "email_address": "jack@example.com",
        "date_sent": "2020-11-25T19:27:42.000Z",
        "status": "PENDING"
    }
]

### Error Handling
- **404**: Unable to find household invitations for member.
```

--------------------------------

### Get Household Details

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/HouseholdGet.html

Retrieves the basic details of a specified household, including its members and points.

```APIDOC
## GET /v2/household/[household_id]

### Description
Returns the basic details of a household.

### Method
GET

### Endpoint
https://[environment]api[client_id].crowdtwist.com/v2/household/[household_id]?api_key=[api_key]

### Parameters
#### Path Parameters
- **household_id** (Integer) - Required - The ID of the household to retrieve.

#### Query Parameters
- **api_key** (String) - Required - Your API key for authentication.

### Request Example
```
GET https://your_environment.api.your_client_id.crowdtwist.com/v2/household/10?api_key=QWERTYUIOP
```

### Response
#### Success Response (200)
- **household_id** (Integer) - The id of this household.
- **name** (String) - The name of this household.
- **date_created** (String) - The date this household was created (ISO 8601 format).
- **redeemable_points** (Integer) - The number of redeemable points currently contributed to this household.
- **members** (Array of member objects) - The members that are currently part of this household.
  - **id** (Integer) - The id of this member (CrowdTwist ID).
  - **date_joined** (String) - The date this member joined the household.
  - **owner** (Boolean) - True if this member is the owner of the household.

#### Response Example
```json
{
    "household_id": 3,
    "name": "John’s Household",
    "date_created": "2020-11-16T23:51:12.000Z",
    "redeemable_points": 200,
    "members": [
        {
            "id": 240835353,
            "date_joined": "2020-11-16T23:51:12.000Z",
            "owner": true
        }
    ]
}
```

#### Error Responses
- **404** - Unable to find household.
```

--------------------------------

### Sample Reward Data Structure (JSON)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Rewards.html

Illustrates a successful response for a single reward, including its properties and configuration. This structure is used for rewards without specific variations.

```json
{
"id": "3182",
"title": "Test reward",
"description": "qa",
"current_quantity": 100,
"num_points": 1,
"date_start": 1480586400,
"date_end": 1483178400,
"date_end_redeemable": null,
"is_enabled": 1,
"category_id": 1498,
"group_id": 2646,
"no_end_date": 0,
"total_quantity": 100,
"max_select_quantity": null,
"max_per_user": 9,
"is_shipping_required": 0,
"is_phone_number_required": 0,
"is_min_age_required": "0",
"min_age": null,
"is_digital_download": 0,
"sweepstake_winners": null,
"extra_data": null,
"reference_id": "46a6sd ",
"color": null,
"size": null,
"total_coupons": 0,
"remaining_coupons": 0,
"additional_images": [],
"image": "http://crowdtwist.com/img/v2/f8ffd787cd6e8ae15724167809969bb1c149228c/w/h/0/image.jpg",
"reward_terms": null,
"min_tier_id": 73,
"freq_cap":1,
"freq_period_id":2,
"freq_period_name":"Calendar Day",
"segment": {
"name":"Canada Members",
"subscription_id":1043
}
}
```

--------------------------------

### Requests to be Tried Later (GET and Authorization)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/CrowdTwistAPIBestPractices.html

Handling for GET and authorization requests that should be stopped during API downtime and retried with new requests upon recovery.

```APIDOC
## Requests to be Tried Later (GET and Authorization)

### Description
These include GET requests and authorization requests. When 5XX errors occur, clients should cease sending requests to the CrowdTwist API, handle the errors client-side with appropriate messaging, and periodically check for API availability. Once the API is back online, new requests must be initiated.

### Authorization Requests

*   **Type:** Not applicable
*   **Timeout:** 30 seconds
*   **Notes:** Clients must handle 5XX responses gracefully and inform users. Authorization requests cannot be retried; a new request must be made when the API is available.

### GET Requests (Examples)

*   Get Activity
*   Get Rewards
*   Get Survey
*   Get Code Redemption
*   Get User Points
*   Get User Activity History

### Details

*   **Type:** Not applicable
*   **Timeout:** 30 seconds
*   **Notes:** Clients are responsible for handling 5XX errors for GET requests with appropriate messaging. These requests must be re-initiated once the API is operational.
```

--------------------------------

### Get Household Invites (API Request)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/HouseholdInviteGet.html

This snippet demonstrates how to make a GET request to the Crowdtwist API to retrieve a household's invitations. It requires the household ID and an API key. The response includes invitation details such as ID, email, date sent, and status.

```bash
curl -X GET \
  'https://[environment]api[client_id].crowdtwist.com/v2/household/[household_id]/invitation?api_key=[api_key]' \
  -H 'Accept: application/json'
```

--------------------------------

### Sample Purchase Request Body - JSON

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Fulfillment.html

This JSON object represents a sample request body for a purchase event. It includes details such as receipt ID, order ID, user ID, total amount, currency, custom data, and a list of purchased items. The 'is_awaiting_fulfillment' flag is used to indicate items that need to be fulfilled.

```json
{
"receipt_id": "receipt123",
"order_id": "order123",
"user_id": "user123",
"total": 119.64,
"subtotal": 110.78,
"date_purchased": "2012-04-23T18:25:43.511+00:00",
"channel_id": 1,
"currency": "USD",
"custom_data": {
"store_id": "store1",
"register_id": "register1",
"cashier_id": "cashier1",
"employee_id": "employee_123"
},
"items": [
{
"sku": "sku_1",
"is_awaiting_fulfillment": true, 
"price": 21.22,
"quantity": 2,
"transaction_id": 2
},
{
"sku": "sku_2",
"price": 3.22,
"quantity": 1,
"transaction_id": 1
}
]
}
```

--------------------------------

### Get Survey Results (legacy)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/SurveyResults.html

Retrieves response data for a specified survey using its ID. Supports pagination for large datasets.

```APIDOC
## GET /v2/survey/[survey_id]/

### Description
Returns response data for a survey.

### Method
GET

### Endpoint
https://[environment]api[client_id].crowdtwist.com/v2/survey/[survey_id]/

### Parameters
#### Path Parameters
- **survey_id** (String) - Required - ID of survey being retrieved

#### Query Parameters
- **api_key** (String) - Required - API key for authentication
- **page** (String) - Optional - Specifies the page number for pagination. Default page size is 100.

### Request Example
```bash
curl -X GET 'https://api.crowdtwist.com/v2/survey/23/?api_key=QWERTYUIOP'
```

### Response
#### Success Response (200)
- **id** (String) - The ID of the survey response.
- **value** (String) - The content of the survey response.
- **image_id** (String) - The ID of the image associated with the response. Multiple IDs are pipe-delimited.
- **image_url** (String) - The URL of the image associated with the response. Multiple URLs are pipe-delimited.

#### Response Example
```json
[
  {
    "id": "45",
    "value": "Drug Store",
    "image_id": null,
    "image_url": null
  },
  {
    "id": "47",
    "value": "Department Store",
    "image_id": "9105ba5937e340fb6bac58e2edd6359e5180b90b",
    "image_url": "https://sample.crowdtwist.com/img/v2/9105ba3456e340fb6bac58e2edd6359e5180b90b/100/100/0/image.jpg"
  }
]
```

#### Error Response
- **error** (String) - A machine-readable code describing the error (e.g., "param_error", "no_data").
- **message** (String) - A short, descriptive sentence detailing the error.

#### Error Response Example
```json
{
  "error": "no_data",
  "message": "Survey not found."
}
```
```

--------------------------------

### Get Household Invites

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/HouseholdInviteGet.html

Retrieves a list of invitations associated with a specific household. This endpoint allows you to view pending, accepted, or rejected invitations.

```APIDOC
## GET /v2/household/[household_id]/invitation

### Description
Returns a household’s invites.

### Method
GET

### Endpoint
https://[environment]api[client_id].crowdtwist.com/v2/household/[household_id]/invitation

### Parameters
#### Path Parameters
- **household_id** (Integer) - Required - The id of the household.

#### Query Parameters
- **api_key** (String) - Required - API key for authentication.

### Request Example
```
GET https://[environment]api[client_id].crowdtwist.com/v2/household/10/invitation?api_key=QWERTYUIOP
```

### Response
#### Success Response (200)
- **invitation_id** (Integer) - The id of this invitation.
- **email_address** (String) - The email address of the invitee.
- **date_sent** (String) - The date this invitation was sent (ISO 8601 format).
- **status** (String) - The status of this invitation. Possible values: "ACCEPTED", "REJECTED", "PENDING", "REMOVED".

#### Response Example
```json
[
    {
        "invitation_id": 12,
        "email_address": "jack@example.com",
        "date_sent": "2020-11-25T19:27:42.000Z",
        "status": "PENDING"
    }
]
```

#### Error Responses
- **404**: Unable to find household.
```

--------------------------------

### Sample Error Response for User Not Found

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserActivityCredit.html

This JSON object illustrates a typical error response when a requested user does not exist in the system. It includes an 'error' code and a descriptive 'message' explaining the issue.

```json
{
  "error": "page_not_found",
  "message": "User does not exist."
}
```

--------------------------------

### Sample Successful User Response (JSON)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserCreate.html

This JSON object represents a successful response after creating or updating a user. It includes detailed user information, engagement metrics, and custom data.

```JSON
{
  "id": 11601,
  "first_name": "Alice",
  "middle_name": null,
  "last_name": "Twist",
  "lang_pref":"en",
  "date_of_birth": null,
  "email_address": "alice@crowdtwist.com",
  "email_is_verified": true,
  "username": "alicetwist",
  "mobile_phone_number": null,
  "third_party_id": null,
  "is_active": true,
  "gender_id": null,
  "gender": null,
  "extra_data": null,
  "continent": "North America",
  "country": "United States",
  "us_region": "Northeast",
  "ca_province": null,
  "state": "NY",
  "city": "New York City",
  "street_address_1": null,
  "street_address_2": null,
  "postal_code": "10010",
  "receive_email_updates": true,
  "date_receive_email_opt_in": 1461706842,
  "date_receive_email_opt_out": null,
  "total_points": 2000,
  "redeemable_points": 2000,
  "num_points_purchased": 0,
  "facebook_access_token": null,
  "facebook_user_id": null,
  "date_fb_token_expires": null,
  "twitter_oauth_token": null,
  "twitter_oauth_token_secret": null,
  "google_access_token": null,
  "google_refresh_token": null,
  "google_user_id": null,
  "yahoo_access_token": null,
  "yahoo_access_token_secret": null,
  "yahoo_session_handle": null,
  "yahoo_user_id": null,
  "inst_access_token": "1021870.a470c0c.b4f7e07fb0224dc8a97d08466a087b4d",
  "inst_username": "crowdtwist_test",
  "inst_user_id": "1021870",
  "activity_stream_opt_in": true,
  "store_id": null,
  "date_last_login": null,
  "date_last_updated": 1461777590,
  "date_created": 1461706842,
  "rank": null,
  "weekly_rank": null,
  "monthly_rank": null,
  "salt": null,
  "hash_algorithm_id": "1",
  "referral_url": "",
  "fan_level": "Bronze",
  "sign_up_channel_id": 1,
  "custom_data": {
    "register_id": "1",
    "cashier_id": "2"
  },
  "password_generated": "0",
  "tier_info": {
    "current_level": {
      "title": "Bronze",
      "min_value": "2000",
      "max_value": "9999"
    },
    "next_level": null,
    "levels_above": [],
    "levels_below": [],
    "date_assigned": null,
    "expiration_date": null,
    "reset_date": null,
    "score_needed_to_reach": null,
    "score_needed_to_maintain": null
  }
}
```

--------------------------------

### GET Crowdtwist Code Redemption Campaign (curl)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/CodeRedemptionCampaign.html

This sample demonstrates how to retrieve details of a code redemption campaign using a GET request with curl. It requires an API key and campaign identifiers.

```curl
curl -X GET \
  https://api.crowdtwist.com/v2/code_redemption_campaign?api_key=[api_key]&id=[id]&id_type=[id_type]
```

--------------------------------

### POST /activities

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Activities-Extended21.html

Creates a new marketing activity with associated tags, segments, and partner information.

```APIDOC
## POST /activities

### Description
Creates a new activity in the CrowdTwist system. This endpoint requires detailed configuration including activity tags, segment eligibility, and partner metadata.

### Method
POST

### Endpoint
/activities

### Parameters
#### Request Body
- **action_tags** (String) - Required - The JavaScript tag used to award points.
- **date_start** (Date) - Required - Start date of activity.
- **date_end** (Date) - Required - End date of activity.
- **min_tier_id** (String) - Required - Minimum tier ID required to perform the activity.
- **public_title** (String) - Required - Member-facing title.
- **public_description** (String) - Required - Member-facing description.
- **show_as_locked_by_tier** (Boolean) - Required - Indicates if the activity is locked (true) or hidden (false).
- **partner_info** (Object) - Required - Partner object containing id and name.
- **activity_tag** (Array) - Required - List of tags associated with the activity.
- **segment** (Object) - Required - Segment object defining eligibility.
- **extra_data** (Object) - Required - Client-defined additional data.

### Request Example
{
  "action_tags": "<tag>",
  "public_title": "Watch A Video",
  "show_as_locked_by_tier": false,
  "partner_info": { "id": 56577, "name": "Acme Car Rentals" },
  "segment": { "name": "New York Members", "eligibility_type": "inclusion" }
}

### Response
#### Success Response (200)
- **status** (String) - Success confirmation.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Get Extended Activity Details (cURL)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/ActivitySearch.html

This cURL command retrieves extended details for a specific activity using its ID and an API key. It demonstrates how to make a GET request to the Crowdtwist API endpoint for activities.

```shell
curl -X GET \
'https://api.crowdtwist.com/v2/activities/26/extended?api_key=QWERTYUIOP'
```

--------------------------------

### Example Referral Link Structure

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/InviteFriends.html

Demonstrates how a client-provided referral URL is combined with a CrowdTwist-generated invite code to form a unique referral link. The invite code is appended as a query string parameter.

```text
https://client.com/signup?_cts_=gD2S1W8P
```

--------------------------------

### Get Extended Activities - cURL Request

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Activities-Extended21.html

This cURL command demonstrates how to make a GET request to retrieve extended activity data from the Crowdtwist API. It requires an API key for authentication. The response will contain paginated activity data.

```bash
curl -X GET \
  https://api.crowdtwist.com/v2.1/activities/extended?api_key=QWERTYUIOP
```

--------------------------------

### Sample User Activity History Response (JSON)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserActivityHistory-Extended21.html

This JSON object represents a successful response for a user's activity history. It details point totals, redemption information, and a list of activities with their associated data, such as name, points, and award dates.

```json
{
"date_start": 1521676800,
"date_end": 1521763200,
"redemptions_point_total": 0,
"redemptions": [],
"activities_point_total": 2400,
"activities": [
{
"activity_id": "1006156",
"name": "test abc",
"title": "testabc",
"description": "qa",
"num_points": 1200,
"base_num_points": "200",
"image": "https://qa-rewards.crowdtwist.com/img/v2/d79b402d3209d59f699d1ae0c7c9ccc1d18b0188/100/100/0/image.jpg",
"category_id": "3",
"category_name": "Interact",
"type_id": "7",
"type_name": "Your Site",
"activity_channel_id": null,
"activity_channel_name": null,
"freq_cap": null,
"freq_period_id": null,
"freq_period_name": null,
"freq_num_required_attempts": null,
"redirect_url": null,
"points_on_click": false,
"action_tags": null,
"date_awarded": 1522355102,
"date_created": 1522355102,
"extra_data": {
"key": "value"
},
"base_extra_data": null,
"min_tier_id": null,
"show_as_locked_by_tier": false,
"public_title": null,
"public_description": null,
"partner_info": {
"id": 4869684,
"name": "Acme Car Rentals"
}
},
{
"activity_id": "215",
"name": "test xyz",
"title": "testxyz",
"description": "testinf",
"num_points": 1200,
"base_num_points": "0",
"image": "https://qa-rewards.crowdtwist.com/img/v2/6a3bcf37640aad552f7bdc256f04898145886575/100/100/0/image.jpg",
"category_id": null,
"category_name": null,
"type_id": null,
"type_name": null,
"activity_channel_id": null,
"activity_channel_name": null,
"freq_cap": null,
"freq_period_id": null,
"freq_period_name": null,
"freq_num_required_attempts": null,
"redirect_url": null,
"points_on_click": false,
"action_tags": null,
"date_awarded": 1522141229,
"date_created": 1522141229,
"extra_data": null,
"base_extra_data": null,
"min_tier_id": null,
"show_as_locked_by_tier": false,
"public_title": "Rewards Redeemed",
"public_description": "Description text",
"partner_info": null
}
]
}
```

--------------------------------

### Sample Partial Fulfillment Request Body - JSON

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Fulfillment.html

This JSON object illustrates a sample request body for a partial fulfillment scenario. It specifies which items from a purchase are being fulfilled by listing them in the 'items' array. Each item includes its SKU, price, quantity, and transaction ID.

```json
{
"items": [
{
"sku": "sku_1", 
"price": 21.22, 
"quantity": 1, 
"transaction_id": 1
},
{
"sku": "sku_2",
"price": 3.22,
"quantity": 1,
"transaction_id": 1
}
]
}
```

--------------------------------

### Log User Activity with Crowdtwist API (curl)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserActivityCredit.html

This sample shows how to log a user activity using a cURL command. It specifies the API endpoint, HTTP method, and includes parameters for API key and user identification type. The request body, containing activity details, is sent separately.

```shell
curl -X POST \
'https://api.crowdtwist.com/v2/users/alice@crowdtwist.com/activities?api_key=QWERTYUIOP&id_type=email'
```

--------------------------------

### Perform Authenticated GET Request to CrowdTwist API

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/HMACAuthentication.html

Demonstrates the structure of an authenticated GET request to the /v2/activities endpoint. It requires X-CT-Authorization and X-CT-Timestamp headers, where the authorization header is generated via HMAC-SHA-256 hashing.

```http
GET https://api.crowdtwist.com/v2/activities

Headers
X-CT-Authorization CTApiV2Auth ABCl3y7r0s5ukCXz5lCJOCrTZ427pjp5:YmQ0YTgyY2QzMTlhYmFiZTU3ZDBhODIyMDQ5YWU4OTg1MDI5ZjgyMjM3NTA5ZDNmMDkxYzgyY2JjN2E2OTQ1Yw==
X-CT-Timestamp 1437659826
```

--------------------------------

### Sample GET Request for User Activities (cURL)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserActivities-Extended.html

This cURL command demonstrates how to retrieve extended user activities from the Crowdtwist API. It requires an API key and specifies the user's email and ID type.

```cURL
curl -X GET \
'https://api.crowdtwist.com/v2/users/alice@crowdtwist.com/activities/extended?api_key=QWERTYUIOP&id_type=email'
```

--------------------------------

### Retrieve Household Details via GET Request

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/HouseholdGet.html

This endpoint retrieves the basic profile of a household, including its name, creation date, redeemable points, and a list of member objects. It requires a valid household_id and an api_key as query parameters.

```json
{
    "household_id": 3,
    "name": "John’s Household",
    "date_created": "2020-11-16T23:51:12.000Z",
    "redeemable_points": 200,
    "members": [
        {
            "id": 240835353,
            "date_joined": "2020-11-16T23:51:12.000Z",
            "owner": true
        }
    ]
}
```

--------------------------------

### Retrieve Survey Details via cURL

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/SurveyDetails21.html

Demonstrates how to fetch survey information using a GET request. It requires a valid API key passed as a query parameter.

```bash
curl -X GET 'https://api.crowdtwist.com/v2.1/survey/1234?api_key=QWERTYUIOP'
```

--------------------------------

### Sample Error Response Body - JSON

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Fulfillment.html

This JSON object demonstrates a sample error response. It provides information about the system that generated the error, the reason for the error, a general description, and a specific message explaining the issue, such as missing required data for fulfillment.

```json
{
"system": "pos",
"reason": "missing_data",
"description": "Missing Data Exception.",
"message": "Fulfillment must include original receipt id to process a fulfillment."
}
```

--------------------------------

### POST /live-push-user-profile

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/PushUserProfile-withTiersv2.html

Sends a user’s profile data to a client-provided endpoint upon update.

```APIDOC
## POST [Client Provided Endpoint]

### Description
Sends a user’s profile every time it’s updated to a client specified endpoint; includes Tiers v2 data.

### Method
POST

### Endpoint
Client provided (must begin with https://)

### Parameters
#### Request Headers
- **Authorization** (String) - Optional - Basic auth (Base64 encoded username:password)
- **x-api-key** (String) - Optional - API key for endpoint access

#### Request Body
- **country** (String) - Required - User’s country code
- **receiveSmsMessages** (Number) - Required - Binary (0/1) for SMS subscription
- **facebookUserId** (String) - Optional - User’s Facebook ID
- **redeemablePoints** (Number) - Required - Current redeemable points
- **postalCode** (String) - Required - User’s postal code
- **tierInfo** (Object) - Required - Object containing tiers v2 data (resetDate, dateReached, scoreNeededToReach, nextLevel, currentLevel, etc.)
- **signUpTypeId** (Number) - Required - Sign up source ID
- **isActive** (Number) - Required - Binary (0/1) user status
- **emailAddress** (String) - Required - User email address
- **dateLastLogin** (Timestamp) - Required - Last login timestamp

### Request Example
{
  "country": "US",
  "receiveSmsMessages": 0,
  "redeemablePoints": 5200,
  "emailAddress": "george15@crowdtwist.com",
  "tierInfo": {
    "currentLevel": {
      "title": "Tier 1",
      "maxValue": 999
    }
  }
}

### Response
#### Success Response (200)
- **third_party_id** (String) - Optional - Captured ID if synchronization is enabled (only available when authentication is not used).

#### Response Example
{
  "third_party_id": "123456789"
}
```

--------------------------------

### Example Request Headers (Conceptual)

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/HMACAuthentication.html

These examples show the required headers for an HMAC-authenticated API request. The 'X-CT-Authorization' header contains the public key and the generated signature, while 'X-CT-Timestamp' provides a time-sensitive element to prevent replay attacks.

```text
X-CT-Authorization: CTApiV2Auth publickey:signature
X-CT-Timestamp: 1505325876486
```

--------------------------------

### GET /rewards

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/UserRewards21.html

Retrieves a paginated list of available rewards from the CrowdTwist system.

```APIDOC
## GET /rewards

### Description
Retrieves a list of rewards available for redemption, including paging metadata and detailed reward attributes.

### Method
GET

### Endpoint
/v2.1/rewards

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.

### Response
#### Success Response (200)
- **paging** (Array) - Paging information including total rewards and page navigation.
- **rewards** (Array) - List of reward objects.

#### Response Example
{
  "paging": {
    "total": 203,
    "pages": 10,
    "next_page": "http://example.ct.com/v2.1/rewards?page=3",
    "prev_page": "http://example.ct.com/v2.1/rewards?page=1"
  },
  "rewards": [
    {
      "id": "64",
      "title": "10% Off Coupon",
      "num_points": 100,
      "is_enabled": true,
      "current_quantity": 750
    }
  ]
}
```

--------------------------------

### GET /v2/activities

Source: https://docs.oracle.com/en/cloud/saas/marketing/crowdtwist-develop/Developers/Activities.html

This endpoint returns the list of active activities for a specific client. It requires an API key for authentication.

```APIDOC
## GET /v2/activities

### Description
This endpoint returns the list of active activities for a specific client. It requires an API key for authentication.

### Method
GET

### Endpoint
https://[environment]api[client_id].crowdtwist.com/v2/activities?api_key=[apikey]

### Parameters
#### Query Parameters
- **api_key** (String) - Required - The API key for authentication.

#### Request Body
This endpoint does not accept a request body.

### Request Example
```
GET https://[environment]api[client_id].crowdtwist.com/v2/activities?api_key=QWERTYP
```

### Response
#### Success Response (200)
- **id** (String) - Required - Internal CrowdTwist activity id.
- **title** (String) - Required - The title of the activity.
- **description** (String) - Required - The description of the activity.
- **num_points** (Integer) - Required - The number of points a user will earn for completing the specified activity.
- **image** (String) - Nullable - The activity icon URL. Null if not present.
- **category_id** (String) - Required - ID of category activity is member of. Null if no category.
- **type_id** (String) - Required - ID indicating the type of activity.
- **extra_data** (Object) - Optional - Extra data set via Control Center. Null if no extra data.
- **date_start** (Integer) - Optional - Start date of activity. Null if not present.
- **date_end** (Integer) - Optional - End date of activity. Null if not present.
- **min_tier_id** (Integer) - Optional - The minimum tier that a user needs to be at in order to perform this activity. Null if no tier id.
- **show_as_locked_by_tier** (Boolean) - Required - Indicates whether the activity is hidden or locked.

#### Response Example
```json
{
  "id": "1006156",
  "title": "Ad Hoc Points",
  "description": "Ad Hoc Points",
  "num_points": 2000,
  "image": "http://www.imagestorage.com/image",
  "category_id": "3",
  "type_id": "7",
  "extra_data": {
    "Test": "Test"
  },
  "date_start": 1508167798,
  "date_end": 1510846197,
  "min_tier_id": 12,
  "show_as_locked_by_tier": false
}
```

#### Error Responses
- **error** (String) - Required - A short form of the error.
- **message** (String) - Required - A detailed message around the error.

**Error Response Codes**
- **4xx** (Input Error): Returned whenever the request is missing required fields, including situations in which the body is malformed.
- **5xx** (Server Error): HTTP error status code is returned due to an error that occurred in the backend.

**Example Error Response (403)**
```json
{
  "error": "invalid_auth",
  "message": "Invalid access credentials."
}
```
```
Tokens:
Raw