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

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

payload = {
"studyId": "<string>",
"participantIds": ["<string>"],
"amountCents": 123,
"customIncentiveOptionId": "<string>",
"customIncentiveValue": "<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,
customIncentiveOptionId: '<string>',
customIncentiveValue: '<string>',
allowDuplicate: true
})
};

fetch('https://api.rallyuxr.com/api/public/v1/incentives/custom/log', 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/custom/log",
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,
'customIncentiveOptionId' => '<string>',
'customIncentiveValue' => '<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/custom/log"

payload := strings.NewReader("{\n \"studyId\": \"<string>\",\n \"participantIds\": [\n \"<string>\"\n ],\n \"amountCents\": 123,\n \"customIncentiveOptionId\": \"<string>\",\n \"customIncentiveValue\": \"<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/custom/log")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"studyId\": \"<string>\",\n \"participantIds\": [\n \"<string>\"\n ],\n \"amountCents\": 123,\n \"customIncentiveOptionId\": \"<string>\",\n \"customIncentiveValue\": \"<string>\",\n \"allowDuplicate\": true\n}")
.asString();
require 'uri'
require 'net/http'

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

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 \"customIncentiveOptionId\": \"<string>\",\n \"customIncentiveValue\": \"<string>\",\n \"allowDuplicate\": true\n}"

response = http.request(request)
puts response.read_body
{
  "success": true,
  "isAsync": true,
  "loggedIncentiveCount": 123,
  "skippedParticipantIds": [
    "<string>"
  ]
}
{
"errors": [
{
"message": "<string>",
"path": [
"<string>"
]
}
]
}
"Unauthorized"
"Forbidden"
"{Resource} not found"
"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

Log the custom incentive configured on a study (for example swag or cash handed out to people outside Rally) against one or more of its participants. Custom incentives are recorded in Rally, not sent; the custom incentive itself comes from the study configuration, with the option / value / amount as the only overrides.

studyId
string
required

The ID of the study the participants belong to

participantIds
string[]
required

The IDs of the study participants to log the custom incentive against. A maximum of 10 participants may be logged per request.

Required array length: 1 - 10 elements
amountCents
integer

Override for the logged value in cents. Only applies when the study's custom incentive is a monetary value. Defaults to the study's configured amount

customIncentiveOptionId
string

Override for the selected custom incentive option. Only applies when the study's custom incentive is single-select. Defaults to the study's configured default option

customIncentiveValue
string

Override for the logged custom incentive value. Only applies when the study's custom incentive is not single-select. Defaults to the study's configured default value

allowDuplicate
boolean

By default, participants who already have an outstanding custom incentive for this study are skipped and returned in skippedParticipantIds. Set to true to log anyway, allowing multiple custom incentives per participant

Response

The custom incentive log was accepted

The result of logging a custom incentive

success
boolean
required

Whether the custom incentive was logged

isAsync
boolean
required

Whether logging is processed asynchronously. Larger requests are queued and processed in the background

loggedIncentiveCount
number

The number of participants the incentive was logged against

skippedParticipantIds
string[]

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