Tracking

Embed
Preview of the card
<a href="https://referalli.com/docs/ref-tracking"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/0181901a-6c00-4455-9cd6-0d7676e214dc/social-card.svg?v=3e7ae33eec8b" alt="Tracking" width="600" height="315"></a>
GEThttps://referalli.com/t/{orgToken}/aff.js
Get the tracking script

The JavaScript snippet for the merchant's site, generated for this tracking token. It records visits, captures ?via=/ref_click_id and the org's referral params, and keeps the attribution context as long as the longest cookie window of the org's active programs. Cached for 5 minutes. Unknown tokens return 404.

Auth: none.

Parameters
orgTokenstringpathrequired
Code samples
cURL
curl -X GET "https://referalli.com/t/{orgToken}/aff.js"
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/aff.js', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/t/{orgToken}/aff.js",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/t/{orgToken}/aff.js", 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/t/{orgToken}/aff.js');
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/t/{orgToken}/aff.js')
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.body
Java
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/t/{orgToken}/aff.js"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 The tracking script, generated for this token.
"string"
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/go/{orgToken}/{code}
Follow a tracked link

Records a click on the link with this code and redirects (302) to its destination with via and ref_click_id appended, plus the program's UTM template. When the program has challengeLinks on, the first response is a small HTML page that runs an invisible JavaScript challenge and comes back with cx. Over the anti-flood limits (60 per link, 30 per IP, refilling) the visitor is still redirected but the click is marked rate-limited and can't attribute. A link without a destination, or an unknown code, is 404.

Auth: none.

Parameters
orgTokenstringpathrequired
codestringpathrequired
cxstringquery
Set by the link challenge page; never sent by hand.
Code samples
cURL
curl -X GET "https://referalli.com/go/{orgToken}/{code}?cx="
TypeScript
const res = await fetch('https://referalli.com/go/{orgToken}/{code}?cx=', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/go/{orgToken}/{code}?cx=",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/go/{orgToken}/{code}?cx=", 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/go/{orgToken}/{code}?cx=');
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/go/{orgToken}/{code}?cx=')
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.body
Java
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/go/{orgToken}/{code}?cx="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
302 Redirects the browser.
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
POSThttps://referalli.com/t/{orgToken}/visit
Record a page visit

Beacon sent by aff.js on each landing. Upserts the visitor (anonId) and, when the page was opened with ?via=<code> and no clickId, records a click for that link. Returns the click id to keep in the browser. CORS open to any origin.

Auth: none.

Parameters
orgTokenstringpathrequired
Request body application/json
anonIdstringrequired
clickIdstring
codestring
urlstring
refererstring
{
  "anonId": "string",
  "clickId": "string",
  "code": "string",
  "url": "string",
  "referer": "string"
}
Code samples
cURL
curl -X POST "https://referalli.com/t/{orgToken}/visit" \
  -H "Content-Type: application/json" \
  -d '{"anonId":"string","clickId":"string","code":"string","url":"string","referer":"string"}'
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/visit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"anonId":"string","clickId":"string","code":"string","url":"string","referer":"string"}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://referalli.com/t/{orgToken}/visit",
    headers={
    "Content-Type": "application/json",
    },
    json={"anonId": "string", "clickId": "string", "code": "string", "url": "string", "referer": "string"},
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/t/{orgToken}/visit", strings.NewReader(`{"anonId":"string","clickId":"string","code":"string","url":"string","referer":"string"}`))
	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/t/{orgToken}/visit');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"anonId":"string","clickId":"string","code":"string","url":"string","referer":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://referalli.com/t/{orgToken}/visit')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"anonId":"string","clickId":"string","code":"string","url":"string","referer":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
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/t/{orgToken}/visit"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"anonId\":\"string\",\"clickId\":\"string\",\"code\":\"string\",\"url\":\"string\",\"referer\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "ok": true,
  "clickId": "string"
}
Schema
okbooleanrequired
clickIdstringrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/t/{orgToken}/codes/{code}
Look up a referral code

Checks whether a link or coupon code is valid in an active program, for an "Invited by …" banner on a sign-up page. Returns only the partner's first name and the friend's reward. Unknown codes, inactive partners and paused programs answer 404 { "valid": false }. Limited to bursts of 30 per IP.

Auth: none.

Parameters
orgTokenstringpathrequired
codestringpathrequired
Code samples
cURL
curl -X GET "https://referalli.com/t/{orgToken}/codes/{code}"
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/codes/{code}', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/t/{orgToken}/codes/{code}",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/t/{orgToken}/codes/{code}", 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/t/{orgToken}/codes/{code}');
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/t/{orgToken}/codes/{code}')
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.body
Java
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/t/{orgToken}/codes/{code}"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "valid": true,
  "partnerDisplayName": "string",
  "refereeReward": {
    "kind": "string",
    "bps": 0,
    "amountMinor": 0,
    "capMinor": 0,
    "currency": "string",
    "on": "string"
  }
}
Schema
validbooleanrequired
partnerDisplayNamestringrequired
First name only.
refereeRewardobjectrequired
Show child parameters
kindstringrequired
bpsinteger
amountMinorinteger
Integer minor units (cents).
capMinorinteger
Integer minor units (cents).
currencystringrequired
onstringrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
POSThttps://referalli.com/t/{orgToken}/identify
Identify a visitor

Links an anonymous visitor (anonId) to your customer id (customerRef) and/or a SHA-256 email hash, so a later POST /v1/referrals/associate can match the visit. Called by aff.js after sign-up.

Auth: none.

Parameters
orgTokenstringpathrequired
Request body application/json
anonIdstringrequired
customerRefstring
emailHashstring
{
  "anonId": "string",
  "customerRef": "string",
  "emailHash": "string"
}
Code samples
cURL
curl -X POST "https://referalli.com/t/{orgToken}/identify" \
  -H "Content-Type: application/json" \
  -d '{"anonId":"string","customerRef":"string","emailHash":"string"}'
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/identify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"anonId":"string","customerRef":"string","emailHash":"string"}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://referalli.com/t/{orgToken}/identify",
    headers={
    "Content-Type": "application/json",
    },
    json={"anonId": "string", "customerRef": "string", "emailHash": "string"},
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/t/{orgToken}/identify", strings.NewReader(`{"anonId":"string","customerRef":"string","emailHash":"string"}`))
	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/t/{orgToken}/identify');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"anonId":"string","customerRef":"string","emailHash":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://referalli.com/t/{orgToken}/identify')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"anonId":"string","customerRef":"string","emailHash":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
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/t/{orgToken}/identify"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"anonId\":\"string\",\"customerRef\":\"string\",\"emailHash\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "ok": true
}
Schema
okbooleanrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/t/{orgToken}/widget.js
Get the referral widget script

The embeddable in-app referral widget, generated for this tracking token. It reads the signed-in customer through GET /t/{orgToken}/widget/me with a token from POST /v1/widget/tokens.

Auth: none.

Parameters
orgTokenstringpathrequired
Code samples
cURL
curl -X GET "https://referalli.com/t/{orgToken}/widget.js"
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/widget.js', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/t/{orgToken}/widget.js",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/t/{orgToken}/widget.js", 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/t/{orgToken}/widget.js');
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/t/{orgToken}/widget.js')
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.body
Java
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/t/{orgToken}/widget.js"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 The in-app referral widget (web component).
"string"
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/t/{orgToken}/widget/me
Read the widget customer's referral data

Called by the widget with Authorization: Widget <token> (a token minted by your backend). Returns the customer's link, code, share URLs, progress, balances and the friend's reward. A token reads only its own partner. 401 when the token is missing, expired or for another merchant.

Auth: none.

Parameters
orgTokenstringpathrequired
Code samples
cURL
curl -X GET "https://referalli.com/t/{orgToken}/widget/me"
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/widget/me', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/t/{orgToken}/widget/me",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/t/{orgToken}/widget/me", 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/t/{orgToken}/widget/me');
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/t/{orgToken}/widget/me')
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.body
Java
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/t/{orgToken}/widget/me"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "program": {
    "id": "string",
    "name": "string"
  },
  "partner": {
    "displayName": "string"
  },
  "code": "string",
  "coupon": "string",
  "link": "string",
  "share": {
    "x": "string",
    "facebook": "string",
    "linkedin": "string",
    "whatsapp": "string",
    "email": "string"
  },
  "progress": {
    "clicks": 0,
    "signups": 0,
    "payingCustomers": 0
  },
  "earnings": [
    {
      "currency": "string",
      "pending": 0,
      "approved": 0,
      "paid": 0
    }
  ],
  "refereeReward": {
    "kind": "string",
    "bps": 0,
    "amountMinor": 0,
    "capMinor": 0,
    "currency": "string",
    "on": "string"
  }
}
Schema
programobjectrequired
Show child parameters
idstringrequired
namestringrequired
partnerobjectrequired
Show child parameters
displayNamestringrequired
codestringrequired
couponstringrequired
linkstringrequired
shareobjectrequired
Show child parameters
xstringrequired
facebookstringrequired
linkedinstringrequired
whatsappstringrequired
emailstringrequired
progressobjectrequired
Show child parameters
clicksintegerrequired
signupsintegerrequired
payingCustomersintegerrequired
earningsobject[]required
Show child parameters
currencystringrequired
pendingintegerrequired
Integer minor units (cents).
approvedintegerrequired
Integer minor units (cents).
paidintegerrequired
Integer minor units (cents).
refereeRewardobjectrequired
Show child parameters
kindstringrequired
bpsinteger
amountMinorinteger
Integer minor units (cents).
capMinorinteger
Integer minor units (cents).
currencystringrequired
onstringrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/t/{orgToken}/mobile/resolve
Resolve a deferred deep link

Called by the mobile SDK on first app open to recover the partner-link click that led to the install, and the destination to route to. Candidates are eligible clicks from the last hour on the caller's IP or its network (/24 IPv4, /64 IPv6) that no app open has claimed. An exact user-agent match is the strongest signal; otherwise the click's browser user agent must agree with the device hint the SDK sends (platform and osVersion, major version compared), and without a hint only a click from the exact same IP matches. The most recent best match is claimed, so each click resolves for one install only; matchType says how it matched. matched: false when nothing qualifies.

Auth: none.

Parameters
orgTokenstringpathrequired
platformstringquery
The device platform, sent by the mobile SDK.
ios | android
osVersionstringquery
The OS version (17.4); only the major version is compared.
Code samples
cURL
curl -X GET "https://referalli.com/t/{orgToken}/mobile/resolve?platform=&osVersion="
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/mobile/resolve?platform=&osVersion=', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/t/{orgToken}/mobile/resolve?platform=&osVersion=",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/t/{orgToken}/mobile/resolve?platform=&osVersion=", 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/t/{orgToken}/mobile/resolve?platform=&osVersion=');
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/t/{orgToken}/mobile/resolve?platform=&osVersion=')
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.body
Java
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/t/{orgToken}/mobile/resolve?platform=&osVersion="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "matched": true,
  "clickId": "string",
  "code": "string",
  "destination": "string",
  "programId": "string",
  "matchType": "user_agent"
}
Schema
matchedbooleanrequired
clickIdstring
codestring
destinationstring
programIdstring
matchTypestring
How the click was matched, strongest first: the exact user agent, the device hint on the same network, or the exact IP alone.
user_agent | device | ip
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
POSThttps://referalli.com/t/{orgToken}/mobile/install
Attribute an app install

Called by the mobile SDK after install to attribute the new customer, through the same engine as POST /v1/referrals/associate. Send the clickId from the deferred deep link, or on Android the raw Play Install Referrer string as referrer (its ref_click_id, or via link code, is read even when URL-encoded or nested). programId is optional when the click or link names it. A referrer with only via records the install as a click on that link. deviceId makes retries idempotent. 400 when no program can be determined.

Auth: none.

Parameters
orgTokenstringpathrequired
Request body application/json
programIdstring
customerRefstringrequired
clickIdstring
referrerstring
deviceIdstring
idempotencyKeystring
{
  "programId": "string",
  "customerRef": "string",
  "clickId": "string",
  "referrer": "string",
  "deviceId": "string",
  "idempotencyKey": "string"
}
Code samples
cURL
curl -X POST "https://referalli.com/t/{orgToken}/mobile/install" \
  -H "Content-Type: application/json" \
  -d '{"programId":"string","customerRef":"string","clickId":"string","referrer":"string","deviceId":"string","idempotencyKey":"string"}'
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/mobile/install', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"programId":"string","customerRef":"string","clickId":"string","referrer":"string","deviceId":"string","idempotencyKey":"string"}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://referalli.com/t/{orgToken}/mobile/install",
    headers={
    "Content-Type": "application/json",
    },
    json={"programId": "string", "customerRef": "string", "clickId": "string", "referrer": "string", "deviceId": "string", "idempotencyKey": "string"},
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/t/{orgToken}/mobile/install", strings.NewReader(`{"programId":"string","customerRef":"string","clickId":"string","referrer":"string","deviceId":"string","idempotencyKey":"string"}`))
	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/t/{orgToken}/mobile/install');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"programId":"string","customerRef":"string","clickId":"string","referrer":"string","deviceId":"string","idempotencyKey":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://referalli.com/t/{orgToken}/mobile/install')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"programId":"string","customerRef":"string","clickId":"string","referrer":"string","deviceId":"string","idempotencyKey":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
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/t/{orgToken}/mobile/install"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"programId\":\"string\",\"customerRef\":\"string\",\"clickId\":\"string\",\"referrer\":\"string\",\"deviceId\":\"string\",\"idempotencyKey\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "attributed": true,
  "referralId": "string",
  "partnerId": "string",
  "programId": "string"
}
Schema
attributedbooleanrequired
referralIdstringrequired
partnerIdstringrequired
programIdstringrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
POSThttps://referalli.com/t/{orgToken}/mobile/event
Report an in-app purchase (retired)

Retired: always 410 gone. Report purchases from your backend with POST /v1/mobile/purchases and an API key, after validating the store receipt.

Auth: none.

Parameters
orgTokenstringpathrequired
Code samples
cURL
curl -X POST "https://referalli.com/t/{orgToken}/mobile/event"
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/mobile/event', {
  method: 'POST',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://referalli.com/t/{orgToken}/mobile/event",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/t/{orgToken}/mobile/event", 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/t/{orgToken}/mobile/event');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
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/t/{orgToken}/mobile/event')
req = Net::HTTP::Post.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
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/t/{orgToken}/mobile/event"))
    .method("POST", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
410 The endpoint was retired. error.code is one of:
Example
{
  "error": {
    "code": "gone",
    "message": "use the replacement the message names",
    "docs_url": "https://referalli.com/docs/errors-and-limits#gone"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/.well-known/apple-app-site-association
Get the iOS universal links file

The Apple App Site Association file for partner links. On a merchant's verified link domain it lists the iOS apps (settings.mobileApp.ios: Team ID and bundle id) of that org's active programs, scoped to /go/{trackingToken}/*; on Referalli's own host it lists every live org's apps, each scoped to its own token's paths. Set the apps with PATCH /v1/programs/{id} (mobileApp).

Auth: none.

Code samples
cURL
curl -X GET "https://referalli.com/.well-known/apple-app-site-association"
TypeScript
const res = await fetch('https://referalli.com/.well-known/apple-app-site-association', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/.well-known/apple-app-site-association",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/.well-known/apple-app-site-association", 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/.well-known/apple-app-site-association');
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/.well-known/apple-app-site-association')
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.body
Java
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/.well-known/apple-app-site-association"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "applinks": {
    "details": [
      {
        "appIDs": [
          null
        ],
        "components": [
          null
        ]
      }
    ]
  }
}
Schema
applinksobjectrequired
Show child parameters
detailsobject[]required
Show child parameters
appIDsstring[]required
componentsobject[]required
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/.well-known/assetlinks.json
Get the Android App Links file

The Digital Asset Links statements for partner links: each Android app (settings.mobileApp.android: package name and signing-certificate SHA-256 fingerprints) of the host's org (or, on Referalli's own host, of every live org) may handle the host's URLs. The app's intent filter limits it to /go/{trackingToken}/.

Auth: none.

Code samples
cURL
curl -X GET "https://referalli.com/.well-known/assetlinks.json"
TypeScript
const res = await fetch('https://referalli.com/.well-known/assetlinks.json', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/.well-known/assetlinks.json",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/.well-known/assetlinks.json", 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/.well-known/assetlinks.json');
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/.well-known/assetlinks.json')
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.body
Java
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/.well-known/assetlinks.json"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
[
  {
    "relation": [
      "string"
    ],
    "target": {
      "namespace": "string",
      "package_name": "string",
      "sha256_cert_fingerprints": [
        "string"
      ]
    }
  }
]
Schema
relationstring[]required
targetobjectrequired
Show child parameters
namespacestringrequired
package_namestringrequired
sha256_cert_fingerprintsstring[]required
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
POSThttps://referalli.com/t/{orgToken}/consent
Record a customer's consent

Records or replaces a customer's consent for the clean room: whether it is granted, its purposes, and zero-party attributes the customer declared (declared). A later call for the same customerRef replaces it.

Auth: none.

Parameters
orgTokenstringpathrequired
Request body application/json
customerRefstringrequired
emailHashstring
purposesstring[]
= []
declaredobject
= {}
grantedboolean
= true
{
  "customerRef": "string",
  "emailHash": "string",
  "purposes": [],
  "declared": {},
  "granted": true
}
Code samples
cURL
curl -X POST "https://referalli.com/t/{orgToken}/consent" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"string","emailHash":"string","purposes":[],"declared":{},"granted":true}'
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/consent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"customerRef":"string","emailHash":"string","purposes":[],"declared":{},"granted":true}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://referalli.com/t/{orgToken}/consent",
    headers={
    "Content-Type": "application/json",
    },
    json={"customerRef": "string", "emailHash": "string", "purposes": [], "declared": {}, "granted": True},
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/t/{orgToken}/consent", strings.NewReader(`{"customerRef":"string","emailHash":"string","purposes":[],"declared":{},"granted":true}`))
	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/t/{orgToken}/consent');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"customerRef":"string","emailHash":"string","purposes":[],"declared":{},"granted":true}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://referalli.com/t/{orgToken}/consent')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"customerRef":"string","emailHash":"string","purposes":[],"declared":{},"granted":true}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
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/t/{orgToken}/consent"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"customerRef\":\"string\",\"emailHash\":\"string\",\"purposes\":[],\"declared\":{},\"granted\":true}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "ok": true,
  "customerRef": "string",
  "granted": true
}
Schema
okbooleanrequired
customerRefstringrequired
grantedbooleanrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
POSThttps://referalli.com/v1/widget/tokens
Mint a referral widget token

Your backend mints a short-lived token (60 to 3600 seconds, default 900) for a signed-in customer, identified by customerRef or partnerExternalRef, for the in-app referral widget. When the program has settings.widget.autoEnroll, a customer who isn't a partner yet is created on demand (send email). The token only reads that partner's own data.

Auth: an API key with partners:write (or full), or a session of any role.

Parameters
Idempotency-Keystringheader
Any 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-idstringheader
With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheader
test 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.
live | test
Request body application/json
programIdstringrequired
customerRefstring
partnerExternalRefstring
emailstring
displayNamestring
ttlSecondsinteger
{
  "programId": "string",
  "customerRef": "string",
  "partnerExternalRef": "string",
  "email": "string",
  "displayName": "string",
  "ttlSeconds": 0
}
Code samples
cURL
curl -X POST "https://referalli.com/v1/widget/tokens" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"programId":"string","customerRef":"string","partnerExternalRef":"string","email":"string","displayName":"string","ttlSeconds":0}'
TypeScript
const res = await fetch('https://referalli.com/v1/widget/tokens', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"programId":"string","customerRef":"string","partnerExternalRef":"string","email":"string","displayName":"string","ttlSeconds":0}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/widget/tokens",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"programId": "string", "customerRef": "string", "partnerExternalRef": "string", "email": "string", "displayName": "string", "ttlSeconds": 0},
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/widget/tokens", strings.NewReader(`{"programId":"string","customerRef":"string","partnerExternalRef":"string","email":"string","displayName":"string","ttlSeconds":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/widget/tokens');
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, '{"programId":"string","customerRef":"string","partnerExternalRef":"string","email":"string","displayName":"string","ttlSeconds":0}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/widget/tokens')
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 = '{"programId":"string","customerRef":"string","partnerExternalRef":"string","email":"string","displayName":"string","ttlSeconds":0}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
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/widget/tokens"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"programId\":\"string\",\"customerRef\":\"string\",\"partnerExternalRef\":\"string\",\"email\":\"string\",\"displayName\":\"string\",\"ttlSeconds\":0}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "token": "string",
  "partnerId": "string",
  "expiresAt": "2024-01-01T00:00:00Z"
}
Schema
tokenstringrequired
partnerIdstringrequired
expiresAtstringrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
POSThttps://referalli.com/v1/embed/tokens
Mint a partner embed token

A 15-minute token for the partner with this email, for the partner stats web component (/embed.js) in your app.

Auth: an API key with links:write (or full), or a session of any role.

Parameters
Idempotency-Keystringheader
Any 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-idstringheader
With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.
referalli-modestringheader
test 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.
live | test
Request body application/json
partnerEmailstringrequired
{
  "partnerEmail": "string"
}
Code samples
cURL
curl -X POST "https://referalli.com/v1/embed/tokens" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"partnerEmail":"string"}'
TypeScript
const res = await fetch('https://referalli.com/v1/embed/tokens', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"partnerEmail":"string"}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/embed/tokens",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"partnerEmail": "string"},
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/embed/tokens", strings.NewReader(`{"partnerEmail":"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/embed/tokens');
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, '{"partnerEmail":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/embed/tokens')
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 = '{"partnerEmail":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
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/embed/tokens"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"partnerEmail\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "token": "string",
  "expiresAt": "2024-01-01T00:00:00Z"
}
Schema
tokenstringrequired
expiresAtstringrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/v1/embed/summary
Read embedded partner stats

Called by the embed component with Authorization: Bearer <embed token>: the partner's name, eligible clicks, active referrals, balances and link codes. 401 for a missing, invalid or expired token.

Auth: none.

Code samples
cURL
curl -X GET "https://referalli.com/v1/embed/summary"
TypeScript
const res = await fetch('https://referalli.com/v1/embed/summary', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/embed/summary",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/embed/summary", 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/embed/summary');
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/embed/summary')
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.body
Java
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/embed/summary"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
Example
{
  "partner": {
    "name": "string",
    "email": "string"
  },
  "clicks": 0,
  "referrals": 0,
  "balances": [
    {
      "currency": "string",
      "pending": 0,
      "approved": 0,
      "paid": 0
    }
  ],
  "links": [
    {
      "code": "string",
      "destinationUrl": "string"
    }
  ]
}
Schema
partnerobjectrequired
Show child parameters
namestringrequired
emailstringrequired
clicksintegerrequired
referralsintegerrequired
balancesobject[]required
Show child parameters
currencystringrequired
pendingintegerrequired
Integer minor units (cents).
approvedintegerrequired
Integer minor units (cents).
paidintegerrequired
Integer minor units (cents).
linksobject[]required
Show child parameters
codestringrequired
destinationUrlstringrequired
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/t/{orgToken}/theme.css
Get the white-label theme stylesheet

The org's theme tokens (--r-* custom properties) as a :root stylesheet, for the portal and embedded widgets.

Auth: none.

Parameters
orgTokenstringpathrequired
Code samples
cURL
curl -X GET "https://referalli.com/t/{orgToken}/theme.css"
TypeScript
const res = await fetch('https://referalli.com/t/{orgToken}/theme.css', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/t/{orgToken}/theme.css",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/t/{orgToken}/theme.css", 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/t/{orgToken}/theme.css');
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/t/{orgToken}/theme.css')
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.body
Java
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/t/{orgToken}/theme.css"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
"string"
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/embed.js
Get the partner stats embed script

A web component (no iframe) that shows a partner their clicks, referred sign-ups, balances and link codes inside the merchant's app. Give it a token from POST /v1/embed/tokens; it reads GET /v1/embed/summary.

Auth: none.

Code samples
cURL
curl -X GET "https://referalli.com/embed.js"
TypeScript
const res = await fetch('https://referalli.com/embed.js', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/embed.js",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/embed.js", 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/embed.js');
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/embed.js')
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.body
Java
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/embed.js"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
"string"
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/embed-signup.js
Get the embedded partner sign-up script

A web component that shows a program's public join card (from GET /v1/public/programs/{handle}) on the merchant's site, with a button to the hosted join page.

Auth: none.

Code samples
cURL
curl -X GET "https://referalli.com/embed-signup.js"
TypeScript
const res = await fetch('https://referalli.com/embed-signup.js', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/embed-signup.js",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/embed-signup.js", 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/embed-signup.js');
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/embed-signup.js')
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.body
Java
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/embed-signup.js"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
"string"
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
GEThttps://referalli.com/lead/{orgToken}/{code}
Show a hosted lead form

A hosted HTML email sign-up form for a partner's link code, for partners to share. It posts back to the same URL.

Auth: none.

Parameters
orgTokenstringpathrequired
codestringpathrequired
Code samples
cURL
curl -X GET "https://referalli.com/lead/{orgToken}/{code}"
TypeScript
const res = await fetch('https://referalli.com/lead/{orgToken}/{code}', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://referalli.com/lead/{orgToken}/{code}",
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/lead/{orgToken}/{code}", 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/lead/{orgToken}/{code}');
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/lead/{orgToken}/{code}')
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.body
Java
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/lead/{orgToken}/{code}"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 OK
"string"
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
POSThttps://referalli.com/lead/{orgToken}/{code}
Submit a hosted lead form

Receives the lead form (form-encoded or JSON email): records a click on the partner's link and the SHA-256 hash of the email as the visitor's identity, so a later POST /v1/referrals/associate with that email hash credits the partner. Only the hash is stored.

Auth: none.

Parameters
orgTokenstringpathrequired
codestringpathrequired
Request body application/x-www-form-urlencoded
emailstringrequired
{
  "email": "string"
}
Code samples
cURL
curl -X POST "https://referalli.com/lead/{orgToken}/{code}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"email":"string"}'
TypeScript
const res = await fetch('https://referalli.com/lead/{orgToken}/{code}', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: JSON.stringify({"email":"string"}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://referalli.com/lead/{orgToken}/{code}",
    headers={
    "Content-Type": "application/x-www-form-urlencoded",
    },
    json={"email": "string"},
)
data = res.json()
Go
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/lead/{orgToken}/{code}", strings.NewReader(`{"email":"string"}`))
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	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/lead/{orgToken}/{code}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"email":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://referalli.com/lead/{orgToken}/{code}')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"email":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
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/lead/{orgToken}/{code}"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"email\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 HTML thank-you page, or {"ok":true} when the request is JSON.
"string"
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"
  }
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The 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
errorobjectrequired
Show child parameters
codestringrequired
messagestringrequired
details
requestIdstring
docs_urlstringrequired
The docs entry for this error code: what it means and how to fix it.
Updated