Programs
Embed
<a href="https://referalli.com/docs/ref-programs"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/9b45927c-14bd-4dc6-8236-7218f7e0ff7a/social-card.svg?v=3e7ae33eec8b" alt="Programs" width="600" height="315"></a>GET
https://referalli.com /v1/programs List programs
The org's programs, oldest first, with their settings.
Auth: an API key with programs:read (or full), or a session of any role.
Parameters
limitintegerqueryItems per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
starting_afterstringqueryA cursor: the id of an item (the previous page's
next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.ending_beforestringqueryA cursor: returns the items before this item id (the previous page). Not with
starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.created[gte]stringqueryOnly items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
created[lte]stringqueryOnly items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
referalli-versionstringheaderThe API version to run the request under (2026-10-21, 2026-11-01). Default: the API key's pinned version, else 2026-10-21. The header name from before the rename is still accepted; this name wins when both are sent.
x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X GET "https://referalli.com/v1/programs?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
-H "referalli-version: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
method: 'GET',
headers: {
'referalli-version': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"GET",
"https://referalli.com/v1/programs?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
headers={
"referalli-version": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://referalli.com/v1/programs?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
req.Header.Set("referalli-version", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
.header("referalli-version", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.
Example
{
"object": "string",
"data": [
{
"id": "string",
"name": "string",
"slug": "string",
"attributionModel": "last_click",
"cookieWindowDays": 0,
"signupToConversionDays": 0,
"termsMd": "string",
"status": "draft",
"publicHandle": "string",
"settings": {
"probabilisticPolicy": "string",
"selfReferralPolicy": "review",
"splitCommissions": true,
"utmTemplate": {},
"allowPaidSearch": true,
"challengeLinks": true,
"settlement": "payout",
"riskPolicy": {
"holdBotScore": null,
"holdDisposableEmail": null,
"holdVelocity": null,
"holdUnverifiedEmail": null,
"holdSelfReferral": null,
"holdRiskScore": null,
"holdHighRiskLevel": null
},
"widget": {
"autoEnroll": null,
"destinationUrl": null
},
"refereeReward": null,
"mobileApp": null
},
"publicPage": {
"pitch": "string",
"autoApprove": true
},
"createdAt": "2024-01-01T00:00:00Z"
}
],
"has_more": true,
"next_cursor": "string"
}Schema
objectstringrequireddataProgram[]requiredShow child parameters
idstringrequirednamestringrequiredslugstringrequiredattributionModelstringrequiredcookieWindowDaysintegerrequiredsignupToConversionDaysintegerrequiredtermsMdstringrequiredstatusstringrequiredpublicHandlestringrequiredsettingsobjectrequiredShow child parameters
probabilisticPolicystringrequiredselfReferralPolicystringrequiredsplitCommissionsbooleanrequiredutmTemplateobjectrequiredallowPaidSearchbooleanrequiredchallengeLinksbooleanrequiredsettlementstringrequiredriskPolicyobjectrequiredwidgetobjectrequiredrefereeRewardGetOpenapiJsonResponsemobileAppobjectrequiredThe mobile apps that open this program's links (universal links / App Links), or null.
publicPageobjectrequiredShow child parameters
pitchstringrequiredautoApprovebooleanrequiredcreatedAtstringrequiredhas_morebooleanrequiredWhether another page follows; pass next_cursor as starting_after to get it.
next_cursorstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/programs Create a program
Creates an affiliate program: its attribution model, cookie window, how long after sign-up a conversion still counts, terms, public page and settings. slug is unique per org. Terms are versioned so partners can be asked to accept new ones. Over the plan's program limit this is 402 payment_required.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
Idempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
namestringrequiredslugstringrequiredattributionModelstringcookieWindowDaysintegersignupToConversionDaysintegertermsMdstringstatusstringpublicHandlestringpublicPageobjectShow child parameters
pitchstringautoApprovebooleanprobabilisticPolicystringselfReferralPolicystringsplitCommissionsbooleanutmTemplateobjectallowPaidSearchbooleanchallengeLinksbooleansettlementstringriskPolicyobjectShow child parameters
holdBotScorenumberholdRiskScorenumberholdHighRiskLevelbooleanholdDisposableEmailbooleanholdVelocityintegerholdUnverifiedEmailbooleanholdSelfReferralbooleanwidgetobjectShow child parameters
autoEnrollbooleandestinationUrlstringmobileAppobjectShow child parameters
iosobjectShow child parameters
teamIdstringrequiredbundleIdstringrequiredandroidobjectShow child parameters
packageNamestringrequiredsha256CertFingerprintsstring[]required{
"name": "string",
"slug": "string",
"attributionModel": "last_click",
"cookieWindowDays": 60,
"signupToConversionDays": 365,
"termsMd": "",
"status": "draft",
"publicHandle": "string",
"publicPage": {
"pitch": "string",
"autoApprove": true
},
"probabilisticPolicy": "auto",
"selfReferralPolicy": "review",
"splitCommissions": true,
"utmTemplate": {},
"allowPaidSearch": true,
"challengeLinks": true,
"settlement": "payout",
"riskPolicy": {
"holdBotScore": 0,
"holdRiskScore": 0,
"holdHighRiskLevel": true,
"holdDisposableEmail": true,
"holdVelocity": 0,
"holdUnverifiedEmail": true,
"holdSelfReferral": true
},
"widget": {
"autoEnroll": true,
"destinationUrl": "string"
},
"mobileApp": {
"ios": {
"teamId": null,
"bundleId": null
},
"android": {
"packageName": null,
"sha256CertFingerprints": null
}
}
}Code samples
cURL
curl -X POST "https://referalli.com/v1/programs" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":60,"signupToConversionDays":365,"termsMd":"","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}'TypeScript
const res = await fetch('https://referalli.com/v1/programs', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":60,"signupToConversionDays":365,"termsMd":"","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}),
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/programs",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"name": "string", "slug": "string", "attributionModel": "last_click", "cookieWindowDays": 60, "signupToConversionDays": 365, "termsMd": "", "status": "draft", "publicHandle": "string", "publicPage": {"pitch": "string", "autoApprove": True}, "probabilisticPolicy": "auto", "selfReferralPolicy": "review", "splitCommissions": True, "utmTemplate": {}, "allowPaidSearch": True, "challengeLinks": True, "settlement": "payout", "riskPolicy": {"holdBotScore": 0, "holdRiskScore": 0, "holdHighRiskLevel": True, "holdDisposableEmail": True, "holdVelocity": 0, "holdUnverifiedEmail": True, "holdSelfReferral": True}, "widget": {"autoEnroll": True, "destinationUrl": "string"}, "mobileApp": {"ios": {"teamId": None, "bundleId": None}, "android": {"packageName": None, "sha256CertFingerprints": None}}},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/programs", strings.NewReader(`{"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":60,"signupToConversionDays":365,"termsMd":"","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":60,"signupToConversionDays":365,"termsMd":"","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":60,"signupToConversionDays":365,"termsMd":"","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("POST", BodyPublishers.ofString("{\"name\":\"string\",\"slug\":\"string\",\"attributionModel\":\"last_click\",\"cookieWindowDays\":60,\"signupToConversionDays\":365,\"termsMd\":\"\",\"status\":\"draft\",\"publicHandle\":\"string\",\"publicPage\":{\"pitch\":\"string\",\"autoApprove\":true},\"probabilisticPolicy\":\"auto\",\"selfReferralPolicy\":\"review\",\"splitCommissions\":true,\"utmTemplate\":{},\"allowPaidSearch\":true,\"challengeLinks\":true,\"settlement\":\"payout\",\"riskPolicy\":{\"holdBotScore\":0,\"holdRiskScore\":0,\"holdHighRiskLevel\":true,\"holdDisposableEmail\":true,\"holdVelocity\":0,\"holdUnverifiedEmail\":true,\"holdSelfReferral\":true},\"widget\":{\"autoEnroll\":true,\"destinationUrl\":\"string\"},\"mobileApp\":{\"ios\":{\"teamId\":null,\"bundleId\":null},\"android\":{\"packageName\":null,\"sha256CertFingerprints\":null}}}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"name": "string",
"slug": "string",
"attributionModel": "last_click",
"cookieWindowDays": 0,
"signupToConversionDays": 0,
"termsMd": "string",
"status": "draft",
"publicHandle": "string",
"settings": {
"probabilisticPolicy": "string",
"selfReferralPolicy": "review",
"splitCommissions": true,
"utmTemplate": {},
"allowPaidSearch": true,
"challengeLinks": true,
"settlement": "payout",
"riskPolicy": {
"holdBotScore": 0,
"holdDisposableEmail": true,
"holdVelocity": 0,
"holdUnverifiedEmail": true,
"holdSelfReferral": true,
"holdRiskScore": 0,
"holdHighRiskLevel": true
},
"widget": {
"autoEnroll": true,
"destinationUrl": "string"
},
"refereeReward": {},
"mobileApp": {
"ios": null,
"android": null
}
},
"publicPage": {
"pitch": "string",
"autoApprove": true
},
"createdAt": "2024-01-01T00:00:00Z"
}Schema
idstringrequirednamestringrequiredslugstringrequiredattributionModelstringrequiredcookieWindowDaysintegerrequiredsignupToConversionDaysintegerrequiredtermsMdstringrequiredstatusstringrequiredpublicHandlestringrequiredsettingsobjectrequiredShow child parameters
probabilisticPolicystringrequiredselfReferralPolicystringrequiredsplitCommissionsbooleanrequiredutmTemplateobjectrequiredallowPaidSearchbooleanrequiredchallengeLinksbooleanrequiredsettlementstringrequiredriskPolicyobjectrequiredShow child parameters
holdBotScorenumberrequiredholdDisposableEmailbooleanrequiredholdVelocityintegerrequiredholdUnverifiedEmailbooleanrequiredholdSelfReferralbooleanrequiredholdRiskScorenumberrequiredholdHighRiskLevelbooleanrequiredwidgetobjectrequiredShow child parameters
autoEnrollbooleanrequireddestinationUrlstringrequiredrefereeRewardGetOpenapiJsonResponsemobileAppobjectrequiredThe mobile apps that open this program's links (universal links / App Links), or null.
Show child parameters
iosobjectandroidobjectpublicPageobjectrequiredShow child parameters
pitchstringrequiredautoApprovebooleanrequiredcreatedAtstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
402 The plan's limit is reached.
error.code is one of:Example
{
"error": {
"code": "payment_required",
"message": "a plan limit or feature",
"docs_url": "https://referalli.com/docs/errors-and-limits#payment_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
GET
https://referalli.com /v1/programs/{id} Get a program
One program with its settings (defaults filled in) and public page.
Auth: an API key with programs:read (or full), or a session of any role.
Parameters
idstringpathrequiredx-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X GET "https://referalli.com/v1/programs/{id}" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}', {
method: 'GET',
headers: {
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"GET",
"https://referalli.com/v1/programs/{id}",
headers={
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://referalli.com/v1/programs/{id}", nil)
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}')
req = Net::HTTP::Get.new(uri)
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}"))
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"name": "string",
"slug": "string",
"attributionModel": "last_click",
"cookieWindowDays": 0,
"signupToConversionDays": 0,
"termsMd": "string",
"status": "draft",
"publicHandle": "string",
"settings": {
"probabilisticPolicy": "string",
"selfReferralPolicy": "review",
"splitCommissions": true,
"utmTemplate": {},
"allowPaidSearch": true,
"challengeLinks": true,
"settlement": "payout",
"riskPolicy": {
"holdBotScore": 0,
"holdDisposableEmail": true,
"holdVelocity": 0,
"holdUnverifiedEmail": true,
"holdSelfReferral": true,
"holdRiskScore": 0,
"holdHighRiskLevel": true
},
"widget": {
"autoEnroll": true,
"destinationUrl": "string"
},
"refereeReward": {},
"mobileApp": {
"ios": null,
"android": null
}
},
"publicPage": {
"pitch": "string",
"autoApprove": true
},
"createdAt": "2024-01-01T00:00:00Z"
}Schema
idstringrequirednamestringrequiredslugstringrequiredattributionModelstringrequiredcookieWindowDaysintegerrequiredsignupToConversionDaysintegerrequiredtermsMdstringrequiredstatusstringrequiredpublicHandlestringrequiredsettingsobjectrequiredShow child parameters
probabilisticPolicystringrequiredselfReferralPolicystringrequiredsplitCommissionsbooleanrequiredutmTemplateobjectrequiredallowPaidSearchbooleanrequiredchallengeLinksbooleanrequiredsettlementstringrequiredriskPolicyobjectrequiredShow child parameters
holdBotScorenumberrequiredholdDisposableEmailbooleanrequiredholdVelocityintegerrequiredholdUnverifiedEmailbooleanrequiredholdSelfReferralbooleanrequiredholdRiskScorenumberrequiredholdHighRiskLevelbooleanrequiredwidgetobjectrequiredShow child parameters
autoEnrollbooleanrequireddestinationUrlstringrequiredrefereeRewardGetOpenapiJsonResponsemobileAppobjectrequiredThe mobile apps that open this program's links (universal links / App Links), or null.
Show child parameters
iosobjectandroidobjectpublicPageobjectrequiredShow child parameters
pitchstringrequiredautoApprovebooleanrequiredcreatedAtstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
PATCH
https://referalli.com /v1/programs/{id} Update a program
Changes any program field or setting; omitted fields keep their value, and publicPage is merged. Changing termsMd records a new terms version. Setting status to paused or archived stops new attribution. mobileApp (iOS Team ID and bundle id, Android package and signing-certificate fingerprints) publishes the program's apps in the universal-links and App Links files on the org's link hosts. Audited.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
namestringslugstringattributionModelstringcookieWindowDaysintegersignupToConversionDaysintegertermsMdstringstatusstringpublicHandlestringpublicPageobjectShow child parameters
pitchstringautoApprovebooleanprobabilisticPolicystringselfReferralPolicystringsplitCommissionsbooleanutmTemplateobjectallowPaidSearchbooleanchallengeLinksbooleansettlementstringriskPolicyobjectShow child parameters
holdBotScorenumberholdRiskScorenumberholdHighRiskLevelbooleanholdDisposableEmailbooleanholdVelocityintegerholdUnverifiedEmailbooleanholdSelfReferralbooleanwidgetobjectShow child parameters
autoEnrollbooleandestinationUrlstringmobileAppobjectShow child parameters
iosobjectShow child parameters
teamIdstringrequiredbundleIdstringrequiredandroidobjectShow child parameters
packageNamestringrequiredsha256CertFingerprintsstring[]required{
"name": "string",
"slug": "string",
"attributionModel": "last_click",
"cookieWindowDays": 0,
"signupToConversionDays": 0,
"termsMd": "string",
"status": "draft",
"publicHandle": "string",
"publicPage": {
"pitch": "string",
"autoApprove": true
},
"probabilisticPolicy": "auto",
"selfReferralPolicy": "review",
"splitCommissions": true,
"utmTemplate": {},
"allowPaidSearch": true,
"challengeLinks": true,
"settlement": "payout",
"riskPolicy": {
"holdBotScore": 0,
"holdRiskScore": 0,
"holdHighRiskLevel": true,
"holdDisposableEmail": true,
"holdVelocity": 0,
"holdUnverifiedEmail": true,
"holdSelfReferral": true
},
"widget": {
"autoEnroll": true,
"destinationUrl": "string"
},
"mobileApp": {
"ios": {
"teamId": null,
"bundleId": null
},
"android": {
"packageName": null,
"sha256CertFingerprints": null
}
}
}Code samples
cURL
curl -X PATCH "https://referalli.com/v1/programs/{id}" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":0,"signupToConversionDays":0,"termsMd":"string","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}'TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}', {
method: 'PATCH',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":0,"signupToConversionDays":0,"termsMd":"string","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}),
});
const data = await res.json();Python
import requests
res = requests.request(
"PATCH",
"https://referalli.com/v1/programs/{id}",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"name": "string", "slug": "string", "attributionModel": "last_click", "cookieWindowDays": 0, "signupToConversionDays": 0, "termsMd": "string", "status": "draft", "publicHandle": "string", "publicPage": {"pitch": "string", "autoApprove": True}, "probabilisticPolicy": "auto", "selfReferralPolicy": "review", "splitCommissions": True, "utmTemplate": {}, "allowPaidSearch": True, "challengeLinks": True, "settlement": "payout", "riskPolicy": {"holdBotScore": 0, "holdRiskScore": 0, "holdHighRiskLevel": True, "holdDisposableEmail": True, "holdVelocity": 0, "holdUnverifiedEmail": True, "holdSelfReferral": True}, "widget": {"autoEnroll": True, "destinationUrl": "string"}, "mobileApp": {"ios": {"teamId": None, "bundleId": None}, "android": {"packageName": None, "sha256CertFingerprints": None}}},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("PATCH", "https://referalli.com/v1/programs/{id}", strings.NewReader(`{"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":0,"signupToConversionDays":0,"termsMd":"string","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":0,"signupToConversionDays":0,"termsMd":"string","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}')
req = Net::HTTP::Patch.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"name":"string","slug":"string","attributionModel":"last_click","cookieWindowDays":0,"signupToConversionDays":0,"termsMd":"string","status":"draft","publicHandle":"string","publicPage":{"pitch":"string","autoApprove":true},"probabilisticPolicy":"auto","selfReferralPolicy":"review","splitCommissions":true,"utmTemplate":{},"allowPaidSearch":true,"challengeLinks":true,"settlement":"payout","riskPolicy":{"holdBotScore":0,"holdRiskScore":0,"holdHighRiskLevel":true,"holdDisposableEmail":true,"holdVelocity":0,"holdUnverifiedEmail":true,"holdSelfReferral":true},"widget":{"autoEnroll":true,"destinationUrl":"string"},"mobileApp":{"ios":{"teamId":null,"bundleId":null},"android":{"packageName":null,"sha256CertFingerprints":null}}}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("PATCH", BodyPublishers.ofString("{\"name\":\"string\",\"slug\":\"string\",\"attributionModel\":\"last_click\",\"cookieWindowDays\":0,\"signupToConversionDays\":0,\"termsMd\":\"string\",\"status\":\"draft\",\"publicHandle\":\"string\",\"publicPage\":{\"pitch\":\"string\",\"autoApprove\":true},\"probabilisticPolicy\":\"auto\",\"selfReferralPolicy\":\"review\",\"splitCommissions\":true,\"utmTemplate\":{},\"allowPaidSearch\":true,\"challengeLinks\":true,\"settlement\":\"payout\",\"riskPolicy\":{\"holdBotScore\":0,\"holdRiskScore\":0,\"holdHighRiskLevel\":true,\"holdDisposableEmail\":true,\"holdVelocity\":0,\"holdUnverifiedEmail\":true,\"holdSelfReferral\":true},\"widget\":{\"autoEnroll\":true,\"destinationUrl\":\"string\"},\"mobileApp\":{\"ios\":{\"teamId\":null,\"bundleId\":null},\"android\":{\"packageName\":null,\"sha256CertFingerprints\":null}}}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"name": "string",
"slug": "string",
"attributionModel": "last_click",
"cookieWindowDays": 0,
"signupToConversionDays": 0,
"termsMd": "string",
"status": "draft",
"publicHandle": "string",
"settings": {
"probabilisticPolicy": "string",
"selfReferralPolicy": "review",
"splitCommissions": true,
"utmTemplate": {},
"allowPaidSearch": true,
"challengeLinks": true,
"settlement": "payout",
"riskPolicy": {
"holdBotScore": 0,
"holdDisposableEmail": true,
"holdVelocity": 0,
"holdUnverifiedEmail": true,
"holdSelfReferral": true,
"holdRiskScore": 0,
"holdHighRiskLevel": true
},
"widget": {
"autoEnroll": true,
"destinationUrl": "string"
},
"refereeReward": {},
"mobileApp": {
"ios": null,
"android": null
}
},
"publicPage": {
"pitch": "string",
"autoApprove": true
},
"createdAt": "2024-01-01T00:00:00Z"
}Schema
idstringrequirednamestringrequiredslugstringrequiredattributionModelstringrequiredcookieWindowDaysintegerrequiredsignupToConversionDaysintegerrequiredtermsMdstringrequiredstatusstringrequiredpublicHandlestringrequiredsettingsobjectrequiredShow child parameters
probabilisticPolicystringrequiredselfReferralPolicystringrequiredsplitCommissionsbooleanrequiredutmTemplateobjectrequiredallowPaidSearchbooleanrequiredchallengeLinksbooleanrequiredsettlementstringrequiredriskPolicyobjectrequiredShow child parameters
holdBotScorenumberrequiredholdDisposableEmailbooleanrequiredholdVelocityintegerrequiredholdUnverifiedEmailbooleanrequiredholdSelfReferralbooleanrequiredholdRiskScorenumberrequiredholdHighRiskLevelbooleanrequiredwidgetobjectrequiredShow child parameters
autoEnrollbooleanrequireddestinationUrlstringrequiredrefereeRewardGetOpenapiJsonResponsemobileAppobjectrequiredThe mobile apps that open this program's links (universal links / App Links), or null.
Show child parameters
iosobjectandroidobjectpublicPageobjectrequiredShow child parameters
pitchstringrequiredautoApprovebooleanrequiredcreatedAtstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
GET
https://referalli.com /v1/programs/{id}/enrollments List program enrollments
The program's enrollments and applications, newest first, each with the partner and a cross-network warning when other merchants banned the same account. Filter with status.
Auth: an API key with programs:read (or full), or a session of any role.
Parameters
idstringpathrequiredstatusstringquerylimitintegerqueryItems per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
starting_afterstringqueryA cursor: the id of an item (the previous page's
next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.ending_beforestringqueryA cursor: returns the items before this item id (the previous page). Not with
starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.created[gte]stringqueryOnly items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
created[lte]stringqueryOnly items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
referalli-versionstringheaderThe API version to run the request under (2026-10-21, 2026-11-01). Default: the API key's pinned version, else 2026-10-21. The header name from before the rename is still accepted; this name wins when both are sent.
x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X GET "https://referalli.com/v1/programs/{id}/enrollments?status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
-H "referalli-version: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/enrollments?status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
method: 'GET',
headers: {
'referalli-version': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"GET",
"https://referalli.com/v1/programs/{id}/enrollments?status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
headers={
"referalli-version": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://referalli.com/v1/programs/{id}/enrollments?status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
req.Header.Set("referalli-version", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/enrollments?status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/enrollments?status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/enrollments?status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
.header("referalli-version", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.
Example
{
"object": "string",
"data": [
{
"id": "string",
"partnerId": "string",
"partnerEmail": "string",
"partnerName": "string",
"status": "string",
"createdAt": "2024-01-01T00:00:00Z",
"networkWarning": {
"flagged": true,
"reason": null,
"bannedByOtherMerchants": 0
}
}
],
"has_more": true,
"next_cursor": "string"
}Schema
objectstringrequireddataobject[]requiredShow child parameters
idstringrequiredpartnerIdstringrequiredpartnerEmailstringrequiredpartnerNamestringrequiredstatusstringrequiredcreatedAtstringrequirednetworkWarningobjectrequiredShow child parameters
flaggedbooleanrequiredreasonstringrequiredbannedByOtherMerchantsintegerrequiredOther merchants that banned this account; 0 below the threshold (2). Never says which.
has_morebooleanrequiredWhether another page follows; pass next_cursor as starting_after to get it.
next_cursorstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/programs/{id}/enrollments Enroll a partner
Enrolls an existing partner in the program, approved at once. Publishes partner.enrolled. 409 when already enrolled.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
partnerIdstringrequired{
"partnerId": "string"
}Code samples
cURL
curl -X POST "https://referalli.com/v1/programs/{id}/enrollments" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"partnerId":"string"}'TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/enrollments', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"partnerId":"string"}),
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/programs/{id}/enrollments",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"partnerId": "string"},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/programs/{id}/enrollments", strings.NewReader(`{"partnerId":"string"}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/enrollments');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"partnerId":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/enrollments')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"partnerId":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/enrollments"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("POST", BodyPublishers.ofString("{\"partnerId\":\"string\"}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"programId": "string",
"partnerId": "string",
"status": "applied"
}Schema
idstringrequiredprogramIdstringrequiredpartnerIdstringrequiredstatusstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/programs/{id}/enrollments/{enrollmentId}/approve Approve an application
Approves a pending application (status: "applied"). Publishes partner.approved. 404 when there is no pending application with that id. Audited.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredenrollmentIdstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X POST "https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/approve" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/approve', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/approve",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/approve", nil)
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/approve');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/approve')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/approve"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.method("POST", BodyPublishers.noBody())
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"status": "string"
}Schema
idstringrequiredstatusstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/programs/{id}/enrollments/{enrollmentId}/reject Reject an application
Rejects a pending application. 404 when there is no pending application with that id. Audited.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredenrollmentIdstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X POST "https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/reject" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/reject', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/reject",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/reject", nil)
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/reject');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/reject')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/enrollments/{enrollmentId}/reject"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.method("POST", BodyPublishers.noBody())
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"status": "string"
}Schema
idstringrequiredstatusstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
GET
https://referalli.com /v1/programs/{id}/groups List partner groups
The program's partner groups with member counts. Archived groups are hidden unless includeArchived=true.
Auth: an API key with programs:read (or full), or a session of any role.
Parameters
idstringpathrequiredincludeArchivedstringquerytrue: include archived groups.
limitintegerqueryItems per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
starting_afterstringqueryA cursor: the id of an item (the previous page's
next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.ending_beforestringqueryA cursor: returns the items before this item id (the previous page). Not with
starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.created[gte]stringqueryOnly items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
created[lte]stringqueryOnly items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
referalli-versionstringheaderThe API version to run the request under (2026-10-21, 2026-11-01). Default: the API key's pinned version, else 2026-10-21. The header name from before the rename is still accepted; this name wins when both are sent.
x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X GET "https://referalli.com/v1/programs/{id}/groups?includeArchived=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
-H "referalli-version: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/groups?includeArchived=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
method: 'GET',
headers: {
'referalli-version': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"GET",
"https://referalli.com/v1/programs/{id}/groups?includeArchived=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
headers={
"referalli-version": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://referalli.com/v1/programs/{id}/groups?includeArchived=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
req.Header.Set("referalli-version", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/groups?includeArchived=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/groups?includeArchived=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/groups?includeArchived=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
.header("referalli-version", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.
Example
{
"object": "string",
"data": [
{
"id": "string",
"programId": "string",
"name": "string",
"base": null,
"holdDays": 0,
"minThresholdMinor": 0,
"payoutCurrency": "string",
"onboardingMessage": "string",
"onboardingChecklist": [
"string"
],
"members": 0,
"archivedAt": "2024-01-01T00:00:00Z",
"createdAt": "2024-01-01T00:00:00Z"
}
],
"has_more": true,
"next_cursor": "string"
}Schema
objectstringrequireddataPartnerGroup[]requiredShow child parameters
idstringrequiredprogramIdstringrequirednamestringrequiredbaseobjectrequiredholdDaysintegerrequiredminThresholdMinorintegerrequiredpayoutCurrencystringrequiredonboardingMessagestringrequiredonboardingCheckliststring[]requiredmembersintegerarchivedAtstringrequiredcreatedAtstringrequiredhas_morebooleanrequiredWhether another page follows; pass next_cursor as starting_after to get it.
next_cursorstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/programs/{id}/groups Create a partner group
A group of partners in a program with its own commission base (or null to keep the program rule's), hold days, payout threshold, payout currency, onboarding message and checklist. Names are unique per program (409).
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
namestringrequiredbaseobjectholdDaysintegerminThresholdMinorintegerpayoutCurrencystringonboardingMessagestringonboardingCheckliststring[]{
"name": "string",
"base": {
"kind": "string",
"bps": 0
},
"holdDays": 0,
"minThresholdMinor": 0,
"payoutCurrency": "string",
"onboardingMessage": "string",
"onboardingChecklist": [
"string"
]
}Code samples
cURL
curl -X POST "https://referalli.com/v1/programs/{id}/groups" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"]}'TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/groups', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"]}),
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/programs/{id}/groups",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"name": "string", "base": {"kind": "string", "bps": 0}, "holdDays": 0, "minThresholdMinor": 0, "payoutCurrency": "string", "onboardingMessage": "string", "onboardingChecklist": ["string"]},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/programs/{id}/groups", strings.NewReader(`{"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"]}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/groups');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"]}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/groups')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"]}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/groups"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("POST", BodyPublishers.ofString("{\"name\":\"string\",\"base\":{\"kind\":\"string\",\"bps\":0},\"holdDays\":0,\"minThresholdMinor\":0,\"payoutCurrency\":\"string\",\"onboardingMessage\":\"string\",\"onboardingChecklist\":[\"string\"]}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"programId": "string",
"name": "string",
"base": {
"kind": "string",
"bps": 0
},
"holdDays": 0,
"minThresholdMinor": 0,
"payoutCurrency": "string",
"onboardingMessage": "string",
"onboardingChecklist": [
"string"
],
"members": 0,
"archivedAt": "2024-01-01T00:00:00Z",
"createdAt": "2024-01-01T00:00:00Z"
}Schema
idstringrequiredprogramIdstringrequirednamestringrequiredbaseobjectrequiredholdDaysintegerrequiredminThresholdMinorintegerrequiredpayoutCurrencystringrequiredonboardingMessagestringrequiredonboardingCheckliststring[]requiredmembersintegerarchivedAtstringrequiredcreatedAtstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
PATCH
https://referalli.com /v1/partner-groups/{id} Update a partner group
Changes a group's terms, or archives it (archived: true); archived groups take no new members.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
namestringbaseobjectholdDaysintegerminThresholdMinorintegerpayoutCurrencystringonboardingMessagestringonboardingCheckliststring[]archivedboolean{
"name": "string",
"base": {
"kind": "string",
"bps": 0
},
"holdDays": 0,
"minThresholdMinor": 0,
"payoutCurrency": "string",
"onboardingMessage": "string",
"onboardingChecklist": [
"string"
],
"archived": true
}Code samples
cURL
curl -X PATCH "https://referalli.com/v1/partner-groups/{id}" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"],"archived":true}'TypeScript
const res = await fetch('https://referalli.com/v1/partner-groups/{id}', {
method: 'PATCH',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"],"archived":true}),
});
const data = await res.json();Python
import requests
res = requests.request(
"PATCH",
"https://referalli.com/v1/partner-groups/{id}",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"name": "string", "base": {"kind": "string", "bps": 0}, "holdDays": 0, "minThresholdMinor": 0, "payoutCurrency": "string", "onboardingMessage": "string", "onboardingChecklist": ["string"], "archived": True},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("PATCH", "https://referalli.com/v1/partner-groups/{id}", strings.NewReader(`{"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"],"archived":true}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/partner-groups/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"],"archived":true}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/partner-groups/{id}')
req = Net::HTTP::Patch.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"name":"string","base":{"kind":"string","bps":0},"holdDays":0,"minThresholdMinor":0,"payoutCurrency":"string","onboardingMessage":"string","onboardingChecklist":["string"],"archived":true}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/partner-groups/{id}"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("PATCH", BodyPublishers.ofString("{\"name\":\"string\",\"base\":{\"kind\":\"string\",\"bps\":0},\"holdDays\":0,\"minThresholdMinor\":0,\"payoutCurrency\":\"string\",\"onboardingMessage\":\"string\",\"onboardingChecklist\":[\"string\"],\"archived\":true}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"programId": "string",
"name": "string",
"base": {
"kind": "string",
"bps": 0
},
"holdDays": 0,
"minThresholdMinor": 0,
"payoutCurrency": "string",
"onboardingMessage": "string",
"onboardingChecklist": [
"string"
],
"members": 0,
"archivedAt": "2024-01-01T00:00:00Z",
"createdAt": "2024-01-01T00:00:00Z"
}Schema
idstringrequiredprogramIdstringrequirednamestringrequiredbaseobjectrequiredholdDaysintegerrequiredminThresholdMinorintegerrequiredpayoutCurrencystringrequiredonboardingMessagestringrequiredonboardingCheckliststring[]requiredmembersintegerarchivedAtstringrequiredcreatedAtstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
PUT
https://referalli.com /v1/programs/{id}/partners/{partnerId}/group Set a partner's group
Puts an enrolled partner in one of the program's groups, or none (groupId: null). A partner is in at most one group per program.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredpartnerIdstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
groupIdstringrequired{
"groupId": "string"
}Code samples
cURL
curl -X PUT "https://referalli.com/v1/programs/{id}/partners/{partnerId}/group" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"groupId":"string"}'TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/partners/{partnerId}/group', {
method: 'PUT',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"groupId":"string"}),
});
const data = await res.json();Python
import requests
res = requests.request(
"PUT",
"https://referalli.com/v1/programs/{id}/partners/{partnerId}/group",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"groupId": "string"},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("PUT", "https://referalli.com/v1/programs/{id}/partners/{partnerId}/group", strings.NewReader(`{"groupId":"string"}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/partners/{partnerId}/group');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"groupId":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/partners/{partnerId}/group')
req = Net::HTTP::Put.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"groupId":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/partners/{partnerId}/group"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("PUT", BodyPublishers.ofString("{\"groupId\":\"string\"}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"partnerId": "string",
"programId": "string",
"groupId": "string"
}Schema
partnerIdstringrequiredprogramIdstringrequiredgroupIdstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
GET
https://referalli.com /v1/programs/{id}/promotions List promotions
The program's promotions, latest start first.
Auth: an API key with programs:read (or full), or a session of any role.
Parameters
idstringpathrequiredlimitintegerqueryItems per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
starting_afterstringqueryA cursor: the id of an item (the previous page's
next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.ending_beforestringqueryA cursor: returns the items before this item id (the previous page). Not with
starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.created[gte]stringqueryOnly items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
created[lte]stringqueryOnly items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
referalli-versionstringheaderThe API version to run the request under (2026-10-21, 2026-11-01). Default: the API key's pinned version, else 2026-10-21. The header name from before the rename is still accepted; this name wins when both are sent.
x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X GET "https://referalli.com/v1/programs/{id}/promotions?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
-H "referalli-version: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/promotions?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
method: 'GET',
headers: {
'referalli-version': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"GET",
"https://referalli.com/v1/programs/{id}/promotions?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
headers={
"referalli-version": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://referalli.com/v1/programs/{id}/promotions?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
req.Header.Set("referalli-version", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/promotions?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/promotions?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/promotions?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
.header("referalli-version", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.
Example
{
"object": "string",
"data": [
{
"id": "string",
"programId": "string",
"name": "string",
"groupId": "string",
"effect": {
"kind": null,
"base": null
},
"startsAt": "2024-01-01T00:00:00Z",
"endsAt": "2024-01-01T00:00:00Z",
"endedAt": "2024-01-01T00:00:00Z",
"status": "scheduled",
"createdAt": "2024-01-01T00:00:00Z"
}
],
"has_more": true,
"next_cursor": "string"
}Schema
objectstringrequireddataPromotion[]requiredShow child parameters
idstringrequiredprogramIdstringrequirednamestringrequiredgroupIdstringrequiredeffectobjectrequiredstartsAtstringrequiredendsAtstringrequiredendedAtstringrequiredstatusstringrequiredcreatedAtstringrequiredhas_morebooleanrequiredWhether another page follows; pass next_cursor as starting_after to get it.
next_cursorstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/programs/{id}/promotions Create a promotion
A time-boxed commission change for the whole program or one group: replace the base rate, or boost it by bps, between startsAt and endsAt. Payments in that window get it.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
namestringrequiredgroupIdstringeffectobjectrequiredstartsAtstringrequiredendsAtstringrequired{
"name": "string",
"groupId": "string",
"effect": {
"kind": "string",
"base": {
"kind": null,
"bps": null
}
},
"startsAt": "2024-01-01T00:00:00Z",
"endsAt": "2024-01-01T00:00:00Z"
}Code samples
cURL
curl -X POST "https://referalli.com/v1/programs/{id}/promotions" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"name":"string","groupId":"string","effect":{"kind":"string","base":{"kind":null,"bps":null}},"startsAt":"2024-01-01T00:00:00Z","endsAt":"2024-01-01T00:00:00Z"}'TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/promotions', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"name":"string","groupId":"string","effect":{"kind":"string","base":{"kind":null,"bps":null}},"startsAt":"2024-01-01T00:00:00Z","endsAt":"2024-01-01T00:00:00Z"}),
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/programs/{id}/promotions",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"name": "string", "groupId": "string", "effect": {"kind": "string", "base": {"kind": None, "bps": None}}, "startsAt": "2024-01-01T00:00:00Z", "endsAt": "2024-01-01T00:00:00Z"},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/programs/{id}/promotions", strings.NewReader(`{"name":"string","groupId":"string","effect":{"kind":"string","base":{"kind":null,"bps":null}},"startsAt":"2024-01-01T00:00:00Z","endsAt":"2024-01-01T00:00:00Z"}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/promotions');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name":"string","groupId":"string","effect":{"kind":"string","base":{"kind":null,"bps":null}},"startsAt":"2024-01-01T00:00:00Z","endsAt":"2024-01-01T00:00:00Z"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/promotions')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"name":"string","groupId":"string","effect":{"kind":"string","base":{"kind":null,"bps":null}},"startsAt":"2024-01-01T00:00:00Z","endsAt":"2024-01-01T00:00:00Z"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/promotions"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("POST", BodyPublishers.ofString("{\"name\":\"string\",\"groupId\":\"string\",\"effect\":{\"kind\":\"string\",\"base\":{\"kind\":null,\"bps\":null}},\"startsAt\":\"2024-01-01T00:00:00Z\",\"endsAt\":\"2024-01-01T00:00:00Z\"}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"programId": "string",
"name": "string",
"groupId": "string",
"effect": {
"kind": "string",
"base": {
"kind": null,
"bps": null
}
},
"startsAt": "2024-01-01T00:00:00Z",
"endsAt": "2024-01-01T00:00:00Z",
"endedAt": "2024-01-01T00:00:00Z",
"status": "scheduled",
"createdAt": "2024-01-01T00:00:00Z"
}Schema
idstringrequiredprogramIdstringrequirednamestringrequiredgroupIdstringrequiredeffectobjectrequiredstartsAtstringrequiredendsAtstringrequiredendedAtstringrequiredstatusstringrequiredcreatedAtstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/promotions/{id}/end End a promotion
Ends a promotion now: payments from this moment on no longer get it.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X POST "https://referalli.com/v1/promotions/{id}/end" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/promotions/{id}/end', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/promotions/{id}/end",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/promotions/{id}/end", nil)
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/promotions/{id}/end');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/promotions/{id}/end')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/promotions/{id}/end"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.method("POST", BodyPublishers.noBody())
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"id": "string",
"programId": "string",
"name": "string",
"groupId": "string",
"effect": {
"kind": "string",
"base": {
"kind": null,
"bps": null
}
},
"startsAt": "2024-01-01T00:00:00Z",
"endsAt": "2024-01-01T00:00:00Z",
"endedAt": "2024-01-01T00:00:00Z",
"status": "scheduled",
"createdAt": "2024-01-01T00:00:00Z"
}Schema
idstringrequiredprogramIdstringrequirednamestringrequiredgroupIdstringrequiredeffectobjectrequiredstartsAtstringrequiredendsAtstringrequiredendedAtstringrequiredstatusstringrequiredcreatedAtstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
PUT
https://referalli.com /v1/programs/{id}/incrementality Set the incrementality holdout
Holds out a random control share of referrals (holdoutBps, up to 5000 = 50%) from being commissioned, so comparing control and treatment conversion measures the true lift partners cause. 0 turns it off.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
holdoutBpsintegerrequired{
"holdoutBps": 0
}Code samples
cURL
curl -X PUT "https://referalli.com/v1/programs/{id}/incrementality" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"holdoutBps":0}'TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/incrementality', {
method: 'PUT',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"holdoutBps":0}),
});
const data = await res.json();Python
import requests
res = requests.request(
"PUT",
"https://referalli.com/v1/programs/{id}/incrementality",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"holdoutBps": 0},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("PUT", "https://referalli.com/v1/programs/{id}/incrementality", strings.NewReader(`{"holdoutBps":0}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/incrementality');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"holdoutBps":0}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/incrementality')
req = Net::HTTP::Put.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"holdoutBps":0}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/incrementality"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("PUT", BodyPublishers.ofString("{\"holdoutBps\":0}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"ok": true,
"holdoutBps": 0
}Schema
okbooleanrequiredholdoutBpsintegerrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
GET
https://referalli.com /v1/programs/{id}/autopricing Get autopricing settings
The program's autopricing configuration, or null when it's off.
Auth: an API key with programs:read (or full), or a session of any role.
Parameters
idstringpathrequiredx-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X GET "https://referalli.com/v1/programs/{id}/autopricing" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/autopricing', {
method: 'GET',
headers: {
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"GET",
"https://referalli.com/v1/programs/{id}/autopricing",
headers={
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://referalli.com/v1/programs/{id}/autopricing", nil)
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/autopricing');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/autopricing')
req = Net::HTTP::Get.new(uri)
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/autopricing"))
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"autopricing": {
"enabled": true,
"targetRoas": 0,
"minBps": 0,
"maxBps": 0,
"objective": "roas",
"targetRoi": 0
}
}Schema
autopricingobjectrequiredNull when self-pricing is off. Configs stored before objectives existed read as roas / targetRoi 2.
Show child parameters
enabledbooleanrequiredtargetRoasnumberrequiredminBpsintegerrequiredmaxBpsintegerrequiredobjectivestringrequiredtargetRoinumberrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
PUT
https://referalli.com /v1/programs/{id}/autopricing Configure autopricing
Self-pricing commissions: a target (targetRoas, or with objective: "roi" a targetRoi) and the minBps/maxBps band partner rates may move within. enabled: false turns it off.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
enabledbooleantargetRoasnumberminBpsintegermaxBpsintegerobjectivestringtargetRoinumber{
"enabled": true,
"targetRoas": 5,
"minBps": 500,
"maxBps": 4000,
"objective": "roas",
"targetRoi": 0
}Code samples
cURL
curl -X PUT "https://referalli.com/v1/programs/{id}/autopricing" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"enabled":true,"targetRoas":5,"minBps":500,"maxBps":4000,"objective":"roas","targetRoi":0}'TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/autopricing', {
method: 'PUT',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"enabled":true,"targetRoas":5,"minBps":500,"maxBps":4000,"objective":"roas","targetRoi":0}),
});
const data = await res.json();Python
import requests
res = requests.request(
"PUT",
"https://referalli.com/v1/programs/{id}/autopricing",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"enabled": True, "targetRoas": 5, "minBps": 500, "maxBps": 4000, "objective": "roas", "targetRoi": 0},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("PUT", "https://referalli.com/v1/programs/{id}/autopricing", strings.NewReader(`{"enabled":true,"targetRoas":5,"minBps":500,"maxBps":4000,"objective":"roas","targetRoi":0}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/autopricing');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"enabled":true,"targetRoas":5,"minBps":500,"maxBps":4000,"objective":"roas","targetRoi":0}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/autopricing')
req = Net::HTTP::Put.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"enabled":true,"targetRoas":5,"minBps":500,"maxBps":4000,"objective":"roas","targetRoi":0}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/autopricing"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("PUT", BodyPublishers.ofString("{\"enabled\":true,\"targetRoas\":5,\"minBps\":500,\"maxBps\":4000,\"objective\":\"roas\",\"targetRoi\":0}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"ok": true,
"autopricing": {}
}Schema
okbooleanrequiredautopricingGetOpenapiJsonResponserequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/programs/{id}/autoprice/run Run autopricing
Moves each partner's rate toward the target and publishes the new rates as partner overrides on a new rule version. Objective roas compares attributed revenue to commission; roi uses each partner's matured referral ROI, holding partners with too few matured referrals or an unknown ROI (listed in held). 400 when autopricing is off, the program has no percent-based rule, or no partner has a known ROI under roi.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Request body application/json
objectivestring{
"objective": "roas"
}Code samples
cURL
curl -X POST "https://referalli.com/v1/programs/{id}/autoprice/run" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>" \
-H "Content-Type: application/json" \
-d '{"objective":"roas"}'TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/autoprice/run', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
'Content-Type': 'application/json',
},
body: JSON.stringify({"objective":"roas"}),
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/programs/{id}/autoprice/run",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
"Content-Type": "application/json",
},
json={"objective": "roas"},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/programs/{id}/autoprice/run", strings.NewReader(`{"objective":"roas"}`))
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/autoprice/run');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"objective":"roas"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/autoprice/run')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"objective":"roas"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/autoprice/run"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.header("Content-Type", "application/json")
.method("POST", BodyPublishers.ofString("{\"objective\":\"roas\"}"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"objective": "roas",
"targetRoas": 0,
"targetRoi": 0,
"changes": [
{
"partnerId": "string",
"fromBps": 0,
"toBps": 0,
"realizedRoas": 0,
"realizedRoi": 0
}
],
"held": [
{
"partnerId": "string",
"reason": "roi_unknown",
"maturedGrants": 0
}
]
}Schema
objectivestringrequiredtargetRoasnumberrequiredtargetRoinumberObjective roi only.
changesobject[]requiredShow child parameters
partnerIdstringrequiredfromBpsintegerrequiredtoBpsintegerrequiredrealizedRoasnumberrequiredRevenue ÷ commission; null under objective roi.
realizedRoinumberObjective roi only: referral ROI over matured referrals, both sides: profit after ÷ (referee credit cost + cash commissions + referrer credit cost).
heldobject[]Objective roi only: partners whose rate was kept, and why.
Show child parameters
partnerIdstringrequiredreasonstringrequiredmaturedGrantsintegerrequiredThe partner's matured referrals in the program (the name predates referral-based ROI).
400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
POST
https://referalli.com /v1/programs/{id}/apply-leveling Apply partner levels
Promotes the program's partners to the highest level their referral count qualifies for (never demotes). Publishes partner.level_up per promotion.
Auth: an API key with programs:write (or full), or a session with role owner, admin.
Parameters
idstringpathrequiredIdempotency-KeystringheaderAny unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with
idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X POST "https://referalli.com/v1/programs/{id}/apply-leveling" \
-H "Idempotency-Key: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/apply-leveling', {
method: 'POST',
headers: {
'Idempotency-Key': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"POST",
"https://referalli.com/v1/programs/{id}/apply-leveling",
headers={
"Idempotency-Key": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://referalli.com/v1/programs/{id}/apply-leveling", nil)
req.Header.Set("Idempotency-Key", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/apply-leveling');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/apply-leveling')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/apply-leveling"))
.header("Idempotency-Key", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.method("POST", BodyPublishers.noBody())
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"evaluated": 0,
"promoted": 0
}Schema
evaluatedintegerrequiredpromotedintegerrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
409 The request conflicts with the current state.
error.code is one of:Example
{
"error": {
"code": "conflict",
"message": "a unique value is taken, or the action would break a rule (the message says which)",
"docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
}
}{
"error": {
"code": "idempotency_in_progress",
"message": "a request with the same `idempotency-key` is still running",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
}
}{
"error": {
"code": "replay",
"message": "a signed auth-connection call reused an id already received",
"docs_url": "https://referalli.com/docs/errors-and-limits#replay"
}
}{
"error": {
"code": "live_mode_only",
"message": "only changeable in live mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
}
}{
"error": {
"code": "test_mode_only",
"message": "only exists in test mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
422 The request cannot be processed as sent.
error.code is one of:Example
{
"error": {
"code": "idempotency_key_reused",
"message": "the `idempotency-key` was used for a different request",
"docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
}
}{
"error": {
"code": "validation_error",
"message": "on the signed auth-connection endpoints",
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
GET
https://referalli.com /v1/programs/{id}/terms-acceptances List terms acceptances
Which partner accepted which version of the program's terms, newest first.
Auth: an API key with programs:read (or full), or a session of any role.
Parameters
idstringpathrequiredlimitintegerqueryItems per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
starting_afterstringqueryA cursor: the id of an item (the previous page's
next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.ending_beforestringqueryA cursor: returns the items before this item id (the previous page). Not with
starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.created[gte]stringqueryOnly items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
created[lte]stringqueryOnly items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.
referalli-versionstringheaderThe API version to run the request under (2026-10-21, 2026-11-01). Default: the API key's pinned version, else 2026-10-21. The header name from before the rename is still accepted; this name wins when both are sent.
x-org-idstringheaderWith a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheadertest runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.Code samples
cURL
curl -X GET "https://referalli.com/v1/programs/{id}/terms-acceptances?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
-H "referalli-version: <value>" \
-H "x-org-id: <value>" \
-H "referalli-mode: <value>"TypeScript
const res = await fetch('https://referalli.com/v1/programs/{id}/terms-acceptances?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
method: 'GET',
headers: {
'referalli-version': '<value>',
'x-org-id': '<value>',
'referalli-mode': '<value>',
},
});
const data = await res.json();Python
import requests
res = requests.request(
"GET",
"https://referalli.com/v1/programs/{id}/terms-acceptances?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
headers={
"referalli-version": "<value>",
"x-org-id": "<value>",
"referalli-mode": "<value>",
},
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://referalli.com/v1/programs/{id}/terms-acceptances?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
req.Header.Set("referalli-version", "<value>")
req.Header.Set("x-org-id", "<value>")
req.Header.Set("referalli-mode", "<value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/terms-acceptances?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/programs/{id}/terms-acceptances?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/programs/{id}/terms-acceptances?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
.header("referalli-version", "<value>")
.header("x-org-id", "<value>")
.header("referalli-mode", "<value>")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.
Example
{
"object": "string",
"data": [
{
"version": 0,
"partnerEmail": "string",
"acceptedAt": "2024-01-01T00:00:00Z"
}
],
"has_more": true,
"next_cursor": "string"
}Schema
objectstringrequireddataobject[]requiredShow child parameters
versionintegerrequiredpartnerEmailstringrequiredacceptedAtstringrequiredhas_morebooleanrequiredWhether another page follows; pass next_cursor as starting_after to get it.
next_cursorstringrequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
401 Missing or invalid credentials.
error.code is one of:Example
{
"error": {
"code": "unauthorized",
"message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
"docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
}
}{
"error": {
"code": "step_up_required",
"message": "a partner with two-factor on must send `x-totp-code`",
"docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
403 Authenticated, but not allowed.
error.code is one of:Example
{
"error": {
"code": "forbidden",
"message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
"docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
}
}{
"error": {
"code": "sso_required",
"message": "this organization requires single sign-on",
"docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
}
}{
"error": {
"code": "access_suspended",
"message": "your identity provider suspended your access and you are the last owner",
"docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
GET
https://referalli.com /v1/public/programs/{handle} Get a program's public page
What a program's public join page shows: the program and merchant names, pitch, cookie window, terms, base commission, branding and whether joining is approved at once. No authentication; only active live programs with a publicHandle are found.
Auth: none.
Parameters
handlestringpathrequiredCode samples
cURL
curl -X GET "https://referalli.com/v1/public/programs/{handle}"TypeScript
const res = await fetch('https://referalli.com/v1/public/programs/{handle}', {
method: 'GET',
});
const data = await res.json();Python
import requests
res = requests.request(
"GET",
"https://referalli.com/v1/public/programs/{handle}",
)
data = res.json()Go
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://referalli.com/v1/public/programs/{handle}", nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/public/programs/{handle}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Ruby
require 'net/http'
require 'uri'
uri = URI('https://referalli.com/v1/public/programs/{handle}')
req = Net::HTTP::Get.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(req)
end
puts res.bodyJava
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://referalli.com/v1/public/programs/{handle}"))
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());Responses
200 OK
Example
{
"handle": "string",
"programId": "string",
"programName": "string",
"merchant": "string",
"trackingToken": "string",
"cookieWindowDays": 0,
"termsMd": "string",
"pitch": "string",
"autoApprove": true,
"commission": {},
"branding": {
"logoUrl": "string",
"theme": {}
}
}Schema
handlestringrequiredprogramIdstringrequiredprogramNamestringrequiredmerchantstringrequiredtrackingTokenstringrequiredcookieWindowDaysintegerrequiredtermsMdstringrequiredpitchstringrequiredautoApprovebooleanrequiredcommissionGetOpenapiJsonResponserequiredbrandingobjectrequiredShow child parameters
logoUrlstringrequiredthemeGetOpenapiJsonResponserequired400 The request is invalid.
error.code is one of:Example
{
"error": {
"code": "validation_error",
"message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
"details": [
{
"code": "invalid_format",
"path": [
"destinationUrl"
],
"message": "Invalid URL"
}
],
"docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
}
}{
"error": {
"code": "mode_mismatch",
"message": "the `referalli-mode` header disagrees with the api key's mode",
"docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
}
}{
"error": {
"code": "bad_request",
"message": "rejected by the http layer before the handler",
"docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
404 No such resource.
error.code is one of:Example
{
"error": {
"code": "not_found",
"message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
"docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
429 Rate limited.
error.code is one of:Example
{
"error": {
"code": "rate_limited",
"message": "an endpoint limit or the per-key quota was exceeded",
"docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
500 Unexpected server error.
error.code is one of:Example
{
"error": {
"code": "internal_error",
"message": "retry with backoff",
"requestId": "req_8f2c1d4e5a6b7c8d",
"docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
default Any other error, in the same envelope.
Example
{
"error": {
"code": "string",
"message": "string",
"details": {},
"requestId": "string",
"docs_url": "string"
}
}Schema
errorobjectrequiredShow child parameters
codestringrequiredmessagestringrequireddetailsrequestIdstringdocs_urlstringrequiredThe docs entry for this error code: what it means and how to fix it.
Updated