Skip to main content
POST
/
incentives
Send an incentive to study participants
curl --request POST \
  --url https://api.rallyuxr.com/api/public/v1/incentives \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "studyId": "<string>",
  "participantIds": [
    "<string>"
  ],
  "amountCents": 123,
  "incentiveBudgetId": "<string>",
  "updateToParticipantStatusId": "<string>",
  "allowDuplicate": true
}
'
import requests

url = "https://api.rallyuxr.com/api/public/v1/incentives"

payload = {
    "studyId": "<string>",
    "participantIds": ["<string>"],
    "amountCents": 123,
    "incentiveBudgetId": "<string>",
    "updateToParticipantStatusId": "<string>",
    "allowDuplicate": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    studyId: '<string>',
    participantIds: ['<string>'],
    amountCents: 123,
    incentiveBudgetId: '<string>',
    updateToParticipantStatusId: '<string>',
    allowDuplicate: true
  })
};

fetch('https://api.rallyuxr.com/api/public/v1/incentives', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rallyuxr.com/api/public/v1/incentives",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'studyId' => '<string>',
    'participantIds' => [
        '<string>'
    ],
    'amountCents' => 123,
    'incentiveBudgetId' => '<string>',
    'updateToParticipantStatusId' => '<string>',
    'allowDuplicate' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rallyuxr.com/api/public/v1/incentives"

	payload := strings.NewReader("{\n  \"studyId\": \"<string>\",\n  \"participantIds\": [\n    \"<string>\"\n  ],\n  \"amountCents\": 123,\n  \"incentiveBudgetId\": \"<string>\",\n  \"updateToParticipantStatusId\": \"<string>\",\n  \"allowDuplicate\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.rallyuxr.com/api/public/v1/incentives")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"studyId\": \"<string>\",\n  \"participantIds\": [\n    \"<string>\"\n  ],\n  \"amountCents\": 123,\n  \"incentiveBudgetId\": \"<string>\",\n  \"updateToParticipantStatusId\": \"<string>\",\n  \"allowDuplicate\": true\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.rallyuxr.com/api/public/v1/incentives")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"studyId\": \"<string>\",\n  \"participantIds\": [\n    \"<string>\"\n  ],\n  \"amountCents\": 123,\n  \"incentiveBudgetId\": \"<string>\",\n  \"updateToParticipantStatusId\": \"<string>\",\n  \"allowDuplicate\": true\n}"

response = http.request(request)
puts response.read_body
{
  "success": true,
  "isAsync": true,
  "bulkActionRequestId": "<string>",
  "hasInsufficientFundsForIncentives": true,
  "totalAvailableBalanceCents": 123,
  "skippedParticipantIds": [
    "<string>"
  ]
}
{
  "errors": [
    {
      "message": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}
"Unauthorized"
"Forbidden"
"Too Many Requests"
"Internal Server Error"

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Send the monetary incentive configured on a study to one or more of its participants. This mirrors the manual "Send Incentive" action in Rally: the incentive amount, email content, and sender all come from the study configuration, with amount / currency as the only overrides. Studies configured with a custom (logged) incentive must use POST /incentives/custom/log instead.

studyId
string
required

The ID of the study the participants belong to

participantIds
string[]
required

The IDs of the study participants to send the incentive to. A maximum of 10 participants may be sent to per request.

Required array length: 1 - 10 elements
amountCents
integer

Override for the incentive value in cents. Defaults to the study's configured incentive amount. Applies to monetary incentives, and to custom incentives configured as a monetary value

currency
enum<string>

Override for the incentive currency. Defaults to the study's configured incentive currency. Applies to monetary incentives

Available options:
AUD,
CAD,
EUR,
GBP,
NZD,
USD
incentiveBudgetId
string

Override for the incentive budget to draw from. Defaults to the study's configured budget

updateToParticipantStatusId
string

When provided, participants are moved to this status after the incentive is sent

allowDuplicate
boolean

By default, participants who already have an outstanding (not canceled or expired) incentive for this study are skipped and returned in skippedParticipantIds. Set to true to send anyway, allowing multiple incentives per participant

Response

The incentive send was accepted

The result of sending an incentive

success
boolean
required

Whether the incentive send was accepted

isAsync
boolean
required

Whether the send is processed asynchronously. Larger sends are queued and processed in the background

bulkActionRequestId
string | null
required

The ID of the background bulk action when the send is processed asynchronously

hasInsufficientFundsForIncentives
boolean

True when the budget does not have enough funds

totalAvailableBalanceCents
number | null

The available budget balance in cents

skippedParticipantIds
string[]

Participants that were skipped because they already had an outstanding incentive for the study. Empty when allowDuplicate is true