The following API calls are available for your integration with Fuel Cycle. To understand how to use these calls and where, please view the workflow. These calls also work in conjunction with redirects.

We've included the following link to review a generic version of the Fuel Cycle API documentation online within Postman. This version is not interactive. View in Postman Documentation

Note: This version does not support calls. The test access key/token is not configured in this file. Please reference the Postman file we provided in onboarding for the live/interactive version.

The API endpoints in the following documentation reference the Fuel Cycle stage environment (see Access the API). All initial development and testing should occur in the stage environment. The API text key and token will be only provisioned for the stage environment initially. Once your integration is finished and reviewed by Fuel Cycle, the API URL can be switched to production (see Launch Your Integration).

Create Study

Description

Use this call to notify Fuel Cycle that a new study was created on your platform. Fuel Cycle will then make this study available to clients to attach to community activities within Fuel Cycle.

Endpoint

POST https://api.fuelcyclestage.com/v1/study

Headers

Key	Value	Description
Key	1	Key-value provisioned by Fuel Cycle (Varies)
Token	{token}	Token value provisioned by Fuel Cycle (Varies)

Body

Key	Value	Description
name	My New Study	Study Name (500 characters max) (Required)
status	ACTIVE	Study Status, predefined values: [INITIATED | ACTIVE | DISABLED] (Required)
retakeEnabled	false	Permit participants to respond to the study multiple times [true | false]. Default: false (Optional)
participationURL	https://www.partner.com/participate	URL to participate in the study (Required). Fuel Cycle will append user parameters and redirect to the end of this URL when the study is fielded.
editURL	https://www.partner.com/edit	URL to modify study parameters on partner platform (Optional)
reportURL	https://www.partner.com/report	URL to view reporting/analysis on partner platform (Optional)

The URLs you pass to Fuel Cycle can optionally include query strings. This enables you to specify parameters. Fuel Cycle will preserve these parameters when we display the URL.

Response Example

{
  "error": null,
  "data": {
    "study": {
      "id": 36,
      "editURL": "https://www.partner.com/edit",
      "status": "ACTIVE",
      "name": "My New Study",
      "lastUpdated": 1527570684385,
      "retakeEnabled": false,
      "reportURL": "https://www.partner.com/report",
      "createdDate": 1527570684384,
      "participationURL": "https://www.partner.com/participate"
    }
  }
}

---

Update Study

Description

Use this call to update study parameters (if changed), referencing the study ID returned in the original Create Study call. Reference the study ID in the URL path. This call follows the same conventions as Create Study.

This call should be used when a published study is no longer active or closed on your platform. The status should be set to DISABLED. This will instruct Fuel Cycle to no longer admit members for participation.

Endpoint

POST https://api.fuelcyclestage.com/v1/study/{id}

Headers

Key	Value	Description
Key	1	Key-value provisioned by Fuel Cycle (Varies)
Token	{token}	Token value provisioned by Fuel Cycle (Varies)

Body

Key	Value	Description
name	My New Study	Study Name (500 characters max) (Required)
status	ACTIVE	Study Status, predefined values: [INITIATED | ACTIVE | DISABLED] (Required)
retakeEnabled	false	Permit participants to respond to the study multiple times [true | false]. Default: false (Optional)
participationURL	https://www.partner.com/participate	URL to participate in the study (Required). Fuel Cycle will append user parameters and redirect to the end of this URL when the study is fielded.
editURL	https://www.partner.com/edit	URL to modify study parameters on partner platform (Optional)
reportURL	https://www.partner.com/report	URL to view reporting/analysis on partner platform (Optional)

Response Example

{
  "error": null,
  "data": {
    "study": {
      "id": 1,
      "editURL": "https://www.partner.com/edit",
      "status": "ACTIVE",
      "name": "My New Study",
      "lastUpdated": 1527570663008,
      "retakeEnabled": false,
      "reportURL": "https://www.partner.com/report",
      "createdDate": 1524083774000,
      "participationURL": "https://www.partner.com/participate"
    }
  }
}

---

Get Study

Description

Use this call to return study parameters, referencing the study ID returned in the original Create Study call. Reference the study ID in the URL path. This call follows the same conventions as Create Study. Related call: Update Study.

Endpoint

GET https://api.fuelcyclestage.com/v1/study/{id}

Headers

Key	Value	Description
Key	1	Key-value provisioned by Fuel Cycle (Varies)
Token	{token}	Token value provisioned by Fuel Cycle (Varies)

Body

None

Response Example

{
  "error": null,
  "data": {
    "study": {
      "id": 1,
      "editURL": "https://www.partner.com/edit",
      "status": "ACTIVE",
      "name": "My New Study",
      "lastUpdated": 1527570663000,
      "retakeEnabled": false,
      "reportURL": "https://www.partner.com/report",
      "createdDate": 1524083774000,
      "participationURL": "https://www.partner.com/participate"
    }
  }
}

---

Get User Data

Description

Use this call to retrieve a participant's pseudo-anonymized profile points (e.g. demographics, attitudes, preferences, etc.) This call references the user ID passed in the redirect URL (See redirects). Recommendations for implementing this are available in the article Update User Data.

Endpoint

https://api.fuelcyclestage.com/v1/user/{user id}

Headers

Key	Value	Description
Key	1	Key-value provisioned by Fuel Cycle (Varies)
Token	{token}	Token value provisioned by Fuel Cycle (Varies)

Body

None

Response Example

Note: The number of key/pairs in the response will vary by client community and even each member. Some communities may return dozens of profile points, others fewer. Additionally, key names and the range of available values may change at any point in time (though tend to be relatively persistent once established in the community). See Updating User Data for more information on profile points in Fuel Cycle.

{
  "error": null,
  "data": {
    "fields": [
      {
        "values": "female",
        "key": "gender"
      },
      {
        "values": "26",
        "key": "age"
      },
      {
        "values": "0",
        "key": "children"
      },
      {
        "values": "bachelors degree",
        "key": "education"
      },
      {
        "values": [
          "50-99"
        ],
        "key": "Income"
      },
      {
        "values": [
          "Single"
        ],
        "key": "martial_Status"
      }
      {
        "values": [
          "Facebook",
          "Instagram",
          "LinkedIn",
          "Snapchat",
          "Twitter"
        ],
        "key": "social_sites"
      },
      {
        "values": [
          "Athleta",
          "Gap",
          "Gucci",
          "Hermes",
          "Victorias Secret",
          "Vans"
        ],
        "key": "fashion_brands"
      },
    ]
  }
}

---

Update Study Track

Description

Use this call to notify Fuel Cycle that a participant has completed the study, by referencing the study track ID attached to the participation URL. This call is optional if the URL redirect method is implemented, or otherwise required.

Endpoint

POST https://api.fuelcyclestage.com/v1/study/track/{id}

Headers

Key	Value	Description
Key	1	Key-value provisioned by Fuel Cycle (Varies)
Token	{token}	Token value provisioned by Fuel Cycle (Varies)

Body

Key	Value	Description
externalReferenceId	PartnerResponseID	Set your identifier that represents a specific user's response to a specific study (Required).
status	INITIATED	Update the response status for the participant (Required). Values: COMPLETED | TERMINATED | FAILED_DATA_QUALITY | FAILED_OVER_QUOTA. See Participation Status codes for additional information.

Response Example

{
  "error": null,
  "data": {
    "studyTrack": {
      "id": 1,
      "externalReferenceId": "PartnerResponseID",
      "startDate": 1524087111000,
      "endDate": 1527571179116
    }
  }
}