Integrations

Embed

<a href="https://referalli.com/docs/ref-integrations"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/64bbe332-c62c-4352-a557-6f04bf52c3f8/social-card.svg?v=3e7ae33eec8b" alt="Integrations" width="600" height="315"></a>

POSThttps://referalli.com/v1/import/{provider}

Import partners from another tool

Imports partners, links and codes from a Rewardful, FirstPromoter, Tolt or PartnerStack CSV export (as a text/csv body or { "csv": "…" }) into a program. dryRun=true reports what would happen; destinationUrl is used when the export has no link column. The tool's referral parameter is added to aff.js so shared links keep crediting. Audited.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

providerstringpathrequired

programIdstringqueryrequired

dryRunbooleanquery

= false

destinationUrlstringquery

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 text/csv

The tool's partner export, as CSV.

"string"

Code samples

cURL

curl -X POST "https://referalli.com/v1/import/{provider}?programId=&dryRun=&destinationUrl=" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: text/csv" \
  -d '"string"'

TypeScript

const res = await fetch('https://referalli.com/v1/import/{provider}?programId=&dryRun=&destinationUrl=', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'text/csv',
  },
  body: JSON.stringify("string"),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/import/{provider}?programId=&dryRun=&destinationUrl=",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "text/csv",
    },
    json="string",
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/import/{provider}?programId=&dryRun=&destinationUrl=", strings.NewReader(`"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", "text/csv")
	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/import/{provider}?programId=&dryRun=&destinationUrl=');
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: text/csv']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '"string"');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/import/{provider}?programId=&dryRun=&destinationUrl=')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'text/csv'
req.body = '"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/import/{provider}?programId=&dryRun=&destinationUrl="))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "text/csv")
    .method("POST", BodyPublishers.ofString("\"string\""))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "partnersCreated": 0,
  "partnersSkipped": 0,
  "linksCreated": 0,
  "couponsCreated": 0,
  "codesSkipped": [
    "string"
  ],
  "referralParams": [
    "string"
  ],
  "unpaidImportedMinor": 0,
  "paidImportedMinor": 0
}

Schema

partnersCreatedintegerrequired

partnersSkippedintegerrequired

linksCreatedintegerrequired

couponsCreatedintegerrequired

codesSkippedstring[]required

Codes another partner in this org already uses.

referralParamsstring[]required

The old tool's link parameter, now read by aff.js.

unpaidImportedMinorintegerrequired

Integer minor units (cents).

paidImportedMinorintegerrequired

Integer minor units (cents).

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/integrations

List integrations

The HubSpot and Segment connections with status, settings and the last test result. Credentials are never returned.

Auth: an API key with integrations:read (or full), or a session with role owner, admin.

Parameters

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

Code samples

cURL

curl -X GET "https://referalli.com/v1/integrations" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/integrations', {
  method: 'GET',
  headers: {
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/integrations",
    headers={
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/integrations", nil)
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/integrations');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/integrations')
req = Net::HTTP::Get.new(uri)
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/integrations"))
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "zapier": {
    "hooks": 0,
    "events": [
      "string"
    ]
  },
  "hubspot": {
    "id": "string",
    "kind": "hubspot",
    "status": "active",
    "config": {},
    "hasCredential": true,
    "lastError": "string",
    "lastSuccessAt": "2024-01-01T00:00:00Z",
    "pausedUntil": "2024-01-01T00:00:00Z",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "segment": {
    "id": "string",
    "kind": "hubspot",
    "status": "active",
    "config": {},
    "hasCredential": true,
    "lastError": "string",
    "lastSuccessAt": "2024-01-01T00:00:00Z",
    "pausedUntil": "2024-01-01T00:00:00Z",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Schema

zapierobjectrequired

Show child parameters

hooksintegerrequired

eventsstring[]required

hubspotIntegrationConnectionrequired

Show child parameters

idstringrequired

kindstringrequired

hubspot | segment

statusstringrequired

active | paused | error

configobjectrequired

hasCredentialbooleanrequired

lastErrorstringrequired

lastSuccessAtstringrequired

pausedUntilstringrequired

createdAtstringrequired

updatedAtstringrequired

segmentIntegrationConnectionrequired

Show child parameters

idstringrequired

kindstringrequired

hubspot | segment

statusstringrequired

active | paused | error

configobjectrequired

hasCredentialbooleanrequired

lastErrorstringrequired

lastSuccessAtstringrequired

pausedUntilstringrequired

createdAtstringrequired

updatedAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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.

PUThttps://referalli.com/v1/integrations/hubspot

Connect HubSpot

Connects HubSpot with your private-app token (required the first time; omit to keep it) to sync partners as contacts and referrals as deals in pipeline, moving them to paidDealStage when they pay. status: "paused" stops syncing.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

Idempotency-Keystringheader

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

tokenstring

pipelinestring

newDealStagestring

paidDealStagestring

statusstring

active | paused

{
  "token": "string",
  "pipeline": "string",
  "newDealStage": "string",
  "paidDealStage": "string",
  "status": "active"
}

Code samples

cURL

curl -X PUT "https://referalli.com/v1/integrations/hubspot" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"token":"string","pipeline":"string","newDealStage":"string","paidDealStage":"string","status":"active"}'

TypeScript

const res = await fetch('https://referalli.com/v1/integrations/hubspot', {
  method: 'PUT',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"token":"string","pipeline":"string","newDealStage":"string","paidDealStage":"string","status":"active"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "PUT",
    "https://referalli.com/v1/integrations/hubspot",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"token": "string", "pipeline": "string", "newDealStage": "string", "paidDealStage": "string", "status": "active"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://referalli.com/v1/integrations/hubspot", strings.NewReader(`{"token":"string","pipeline":"string","newDealStage":"string","paidDealStage":"string","status":"active"}`))
	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/integrations/hubspot');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"token":"string","pipeline":"string","newDealStage":"string","paidDealStage":"string","status":"active"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/integrations/hubspot')
req = Net::HTTP::Put.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"token":"string","pipeline":"string","newDealStage":"string","paidDealStage":"string","status":"active"}'
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/integrations/hubspot"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("PUT", BodyPublishers.ofString("{\"token\":\"string\",\"pipeline\":\"string\",\"newDealStage\":\"string\",\"paidDealStage\":\"string\",\"status\":\"active\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "kind": "hubspot",
  "status": "active",
  "config": {},
  "hasCredential": true,
  "lastError": "string",
  "lastSuccessAt": "2024-01-01T00:00:00Z",
  "pausedUntil": "2024-01-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

kindstringrequired

hubspot | segment

statusstringrequired

active | paused | error

configobjectrequired

hasCredentialbooleanrequired

lastErrorstringrequired

lastSuccessAtstringrequired

pausedUntilstringrequired

createdAtstringrequired

updatedAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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.

PUThttps://referalli.com/v1/integrations/segment

Connect Segment

Connects a Segment source with its writeKey (required the first time) and sends referral, commission, payout and partner events as track calls; events limits which topics (null for all).

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

Idempotency-Keystringheader

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

writeKeystring

eventsstring[]

statusstring

active | paused

{
  "writeKey": "string",
  "events": [
    "referral.created"
  ],
  "status": "active"
}

Code samples

cURL

curl -X PUT "https://referalli.com/v1/integrations/segment" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"writeKey":"string","events":["referral.created"],"status":"active"}'

TypeScript

const res = await fetch('https://referalli.com/v1/integrations/segment', {
  method: 'PUT',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"writeKey":"string","events":["referral.created"],"status":"active"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "PUT",
    "https://referalli.com/v1/integrations/segment",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"writeKey": "string", "events": ["referral.created"], "status": "active"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://referalli.com/v1/integrations/segment", strings.NewReader(`{"writeKey":"string","events":["referral.created"],"status":"active"}`))
	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/integrations/segment');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"writeKey":"string","events":["referral.created"],"status":"active"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/integrations/segment')
req = Net::HTTP::Put.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"writeKey":"string","events":["referral.created"],"status":"active"}'
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/integrations/segment"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("PUT", BodyPublishers.ofString("{\"writeKey\":\"string\",\"events\":[\"referral.created\"],\"status\":\"active\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "kind": "hubspot",
  "status": "active",
  "config": {},
  "hasCredential": true,
  "lastError": "string",
  "lastSuccessAt": "2024-01-01T00:00:00Z",
  "pausedUntil": "2024-01-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

kindstringrequired

hubspot | segment

statusstringrequired

active | paused | error

configobjectrequired

hasCredentialbooleanrequired

lastErrorstringrequired

lastSuccessAtstringrequired

pausedUntilstringrequired

createdAtstringrequired

updatedAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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.

DELETEhttps://referalli.com/v1/integrations/{kind}

Disconnect an integration

Removes the HubSpot or Segment connection and its stored credential.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

kindstringpathrequired

Idempotency-Keystringheader

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

Code samples

cURL

curl -X DELETE "https://referalli.com/v1/integrations/{kind}" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/integrations/{kind}', {
  method: 'DELETE',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "DELETE",
    "https://referalli.com/v1/integrations/{kind}",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://referalli.com/v1/integrations/{kind}", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/integrations/{kind}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/integrations/{kind}')
req = Net::HTTP::Delete.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/integrations/{kind}"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("DELETE", BodyPublishers.noBody())
    .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"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/integrations/hubspot/test

Test the HubSpot connection

Checks the token against HubSpot and (unless setupProperties: false) creates the custom properties the sync uses. Returns ok and the error, if any, rather than failing.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

Idempotency-Keystringheader

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

setupPropertiesboolean

= true

{
  "setupProperties": true
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/integrations/hubspot/test" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"setupProperties":true}'

TypeScript

const res = await fetch('https://referalli.com/v1/integrations/hubspot/test', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"setupProperties":true}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/integrations/hubspot/test",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"setupProperties": True},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/integrations/hubspot/test", strings.NewReader(`{"setupProperties":true}`))
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/integrations/hubspot/test');
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, '{"setupProperties":true}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/integrations/hubspot/test')
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 = '{"setupProperties":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/v1/integrations/hubspot/test"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"setupProperties\":true}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "portalId": 0,
  "createdProperties": [
    "string"
  ],
  "error": "string"
}

Schema

okbooleanrequired

portalIdintegerrequired

createdPropertiesstring[]required

errorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/integrations/segment/test

Test the Segment connection

Sends one test track event with the write key and reports whether Segment accepted it.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

Idempotency-Keystringheader

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

Code samples

cURL

curl -X POST "https://referalli.com/v1/integrations/segment/test" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/integrations/segment/test', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/integrations/segment/test",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/integrations/segment/test", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/integrations/segment/test');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/integrations/segment/test')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/integrations/segment/test"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("POST", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "error": "string"
}

Schema

okbooleanrequired

errorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/integrations/deliveries

List integration deliveries

What was sent to Zapier, HubSpot and Segment, newest first, filtered by kind and status.

Auth: an API key with integrations:read (or full), or a session with role owner, admin.

Parameters

kindstringquery

zapier | hubspot | segment

statusstringquery

pending | sent | failed | skipped

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

The API version to run the request under (2026-10-21, 2026-11-01). Default: the API key's pinned version, else 2026-10-21. The header name from before the rename is still accepted; this name wins when both are sent.

2026-10-21 | 2026-11-01

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

Code samples

cURL

curl -X GET "https://referalli.com/v1/integrations/deliveries?kind=&status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/integrations/deliveries?kind=&status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/integrations/deliveries?kind=&status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/integrations/deliveries?kind=&status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/integrations/deliveries?kind=&status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/integrations/deliveries?kind=&status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/integrations/deliveries?kind=&status=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "id": "string",
      "kind": "zapier",
      "targetId": "string",
      "eventId": "string",
      "topic": "string",
      "status": "pending",
      "attempts": 0,
      "nextAt": "2024-01-01T00:00:00Z",
      "lastError": "string",
      "sentAt": "2024-01-01T00:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataIntegrationDelivery[]required

Show child parameters

idstringrequired

kindstringrequired

zapier | hubspot | segment

targetIdstringrequired

eventIdstringrequired

topicstringrequired

statusstringrequired

pending | sent | failed | skipped

attemptsintegerrequired

nextAtstringrequired

lastErrorstringrequired

sentAtstringrequired

createdAtstringrequired

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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/integrations/deliveries/{id}/retry

Retry an integration delivery

Queues a failed or skipped delivery again. 404 when there is no failed or skipped delivery with that id.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

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

Code samples

cURL

curl -X POST "https://referalli.com/v1/integrations/deliveries/{id}/retry" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/integrations/deliveries/{id}/retry', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/integrations/deliveries/{id}/retry",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/integrations/deliveries/{id}/retry", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/integrations/deliveries/{id}/retry');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/integrations/deliveries/{id}/retry')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/integrations/deliveries/{id}/retry"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("POST", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "kind": "zapier",
  "targetId": "string",
  "eventId": "string",
  "topic": "string",
  "status": "pending",
  "attempts": 0,
  "nextAt": "2024-01-01T00:00:00Z",
  "lastError": "string",
  "sentAt": "2024-01-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

kindstringrequired

zapier | hubspot | segment

targetIdstringrequired

eventIdstringrequired

topicstringrequired

statusstringrequired

pending | sent | failed | skipped

attemptsintegerrequired

nextAtstringrequired

lastErrorstringrequired

sentAtstringrequired

createdAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/zapier/events

List Zapier trigger events

The event keys Zapier triggers can subscribe to.

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

Parameters

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

Code samples

cURL

curl -X GET "https://referalli.com/v1/zapier/events" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/zapier/events', {
  method: 'GET',
  headers: {
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/zapier/events",
    headers={
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/zapier/events", nil)
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/zapier/events');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/zapier/events')
req = Net::HTTP::Get.new(uri)
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/zapier/events"))
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

[
  {
    "key": "string"
  }
]

Schema

keystringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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/v1/zapier/hooks

List Zapier hooks

Active Zapier REST hook subscriptions, newest first.

Auth: an API key with integrations:read (or full), or a session with role owner, admin.

Parameters

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

2026-10-21 | 2026-11-01

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

Code samples

cURL

curl -X GET "https://referalli.com/v1/zapier/hooks?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/zapier/hooks?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/zapier/hooks?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/zapier/hooks?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/zapier/hooks?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/zapier/hooks?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/zapier/hooks?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "id": "string",
      "event": "string",
      "target_url": "string",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataZapierHook[]required

Show child parameters

idstringrequired

eventstringrequired

target_urlstringrequired

createdAtstringrequired

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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/zapier/hooks

Subscribe a Zapier hook

REST hook subscribe, called by Zapier when a Zap turns on: events of event are posted to the HTTPS target_url.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

Idempotency-Keystringheader

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

target_urlstringrequired

eventstringrequired

{
  "target_url": "string",
  "event": "referral.created"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/zapier/hooks" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"string","event":"referral.created"}'

TypeScript

const res = await fetch('https://referalli.com/v1/zapier/hooks', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"target_url":"string","event":"referral.created"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/zapier/hooks",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"target_url": "string", "event": "referral.created"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/zapier/hooks", strings.NewReader(`{"target_url":"string","event":"referral.created"}`))
	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/zapier/hooks');
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, '{"target_url":"string","event":"referral.created"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/zapier/hooks')
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 = '{"target_url":"string","event":"referral.created"}'
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/zapier/hooks"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"target_url\":\"string\",\"event\":\"referral.created\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "event": "string",
  "target_url": "string",
  "createdAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

eventstringrequired

target_urlstringrequired

createdAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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.

DELETEhttps://referalli.com/v1/zapier/hooks/{id}

Unsubscribe a Zapier hook

REST hook unsubscribe, called by Zapier when a Zap turns off.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

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

Code samples

cURL

curl -X DELETE "https://referalli.com/v1/zapier/hooks/{id}" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/zapier/hooks/{id}', {
  method: 'DELETE',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "DELETE",
    "https://referalli.com/v1/zapier/hooks/{id}",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://referalli.com/v1/zapier/hooks/{id}", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/zapier/hooks/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/zapier/hooks/{id}')
req = Net::HTTP::Delete.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/zapier/hooks/{id}"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("DELETE", BodyPublishers.noBody())
    .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"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/zapier/triggers/{event}

Poll a Zapier trigger

Zapier polling and sample data: the latest limit events of that kind, newest first, in the shape the hook delivers. Always a plain array (Zapier's contract), whatever the API version.

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

Parameters

eventstringpathrequired

limitintegerquery

= 25

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

Code samples

cURL

curl -X GET "https://referalli.com/v1/zapier/triggers/{event}?limit=" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/zapier/triggers/{event}?limit=', {
  method: 'GET',
  headers: {
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/zapier/triggers/{event}?limit=",
    headers={
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/zapier/triggers/{event}?limit=", nil)
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/zapier/triggers/{event}?limit=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/zapier/triggers/{event}?limit=')
req = Net::HTTP::Get.new(uri)
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/zapier/triggers/{event}?limit="))
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

[
  {
    "id": "string",
    "event": "string",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Schema

idstringrequired

eventstringrequired

createdAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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/v1/auth/connections

List auth connections

Auth-platform connections with provider, program, status, signature version and rotation state. Secrets are never returned.

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

Parameters

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

2026-10-21 | 2026-11-01

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

Code samples

cURL

curl -X GET "https://referalli.com/v1/auth/connections?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/auth/connections?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/auth/connections?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/auth/connections?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/auth/connections?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "id": "string",
      "provider": "clerk",
      "programId": "string",
      "name": "string",
      "status": "string",
      "createdAt": "2024-01-01T00:00:00Z",
      "rotation": {
        "inProgress": true,
        "previousSecretExpiresAt": "2024-01-01T00:00:00Z"
      },
      "instanceId": "string",
      "autoEnrollUsers": true,
      "destinationUrl": "string",
      "signatureVersion": "v1+v2",
      "requiresV2": true
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataAuthConnection[]required

Show child parameters

idstringrequired

providerstringrequired

programIdstringrequired

namestringrequired

statusstringrequired

createdAtstringrequired

rotationobjectrequired

Show child parameters

inProgressbooleanrequired

previousSecretExpiresAtstring

instanceIdstring

Signed-protocol connections: the Atlas instance, or a custom label.

autoEnrollUsersboolean

destinationUrlstring

signatureVersionstring

v1+v2 | v2

requiresV2boolean

True once signatureVersion is v2 or the connection has seen a v2 call.

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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/auth/connections

Connect an auth platform

Connects your sign-up system so new users are attributed server-side without calling associate: clerk, supabase, workos or generic receive the platform's user webhooks at the returned URL; atlas and custom call the signed protocol endpoints under /v1/auth/connections/{id}/. autoEnrollUsers makes every new user a partner too. Returns the signing secret once. 409 when an Atlas instance already has a connection.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

Idempotency-Keystringheader

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

providerstringrequired

programIdstringrequired

instanceIdstring

autoEnrollUsersboolean

= false

destinationUrlstring

namestring

secretstring

keysobject

Show child parameters

referralTokenstring

anonIdstring

couponCodestring

programIdstring

autoEnrollstring

{
  "provider": "clerk",
  "programId": "string",
  "instanceId": "string",
  "autoEnrollUsers": false,
  "destinationUrl": "string",
  "name": "",
  "secret": "string",
  "keys": {
    "referralToken": "string",
    "anonId": "string",
    "couponCode": "string",
    "programId": "string",
    "autoEnroll": "string"
  }
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"provider":"clerk","programId":"string","instanceId":"string","autoEnrollUsers":false,"destinationUrl":"string","name":"","secret":"string","keys":{"referralToken":"string","anonId":"string","couponCode":"string","programId":"string","autoEnroll":"string"}}'

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"provider":"clerk","programId":"string","instanceId":"string","autoEnrollUsers":false,"destinationUrl":"string","name":"","secret":"string","keys":{"referralToken":"string","anonId":"string","couponCode":"string","programId":"string","autoEnroll":"string"}}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"provider": "clerk", "programId": "string", "instanceId": "string", "autoEnrollUsers": False, "destinationUrl": "string", "name": "", "secret": "string", "keys": {"referralToken": "string", "anonId": "string", "couponCode": "string", "programId": "string", "autoEnroll": "string"}},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections", strings.NewReader(`{"provider":"clerk","programId":"string","instanceId":"string","autoEnrollUsers":false,"destinationUrl":"string","name":"","secret":"string","keys":{"referralToken":"string","anonId":"string","couponCode":"string","programId":"string","autoEnroll":"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/auth/connections');
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, '{"provider":"clerk","programId":"string","instanceId":"string","autoEnrollUsers":false,"destinationUrl":"string","name":"","secret":"string","keys":{"referralToken":"string","anonId":"string","couponCode":"string","programId":"string","autoEnroll":"string"}}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections')
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 = '{"provider":"clerk","programId":"string","instanceId":"string","autoEnrollUsers":false,"destinationUrl":"string","name":"","secret":"string","keys":{"referralToken":"string","anonId":"string","couponCode":"string","programId":"string","autoEnroll":"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/auth/connections"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"provider\":\"clerk\",\"programId\":\"string\",\"instanceId\":\"string\",\"autoEnrollUsers\":false,\"destinationUrl\":\"string\",\"name\":\"\",\"secret\":\"string\",\"keys\":{\"referralToken\":\"string\",\"anonId\":\"string\",\"couponCode\":\"string\",\"programId\":\"string\",\"autoEnroll\":\"string\"}}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "provider": "string",
  "secret": "string",
  "webhookUrl": "string",
  "metadataKeys": {},
  "programId": "string",
  "instanceId": "string",
  "autoEnrollUsers": true,
  "destinationUrl": "string",
  "signupsUrl": "string",
  "eraseUrl": "string",
  "exportUrl": "string"
}

Schema

idstringrequired

providerstringrequired

secretstringrequired

Returned only here.

webhookUrlstring

Webhook connectors: Clerk, Supabase, WorkOS, generic.

metadataKeysobject

programIdstring

Signed-protocol connections (atlas, custom).

instanceIdstring

autoEnrollUsersboolean

destinationUrlstring

signupsUrlstring

eraseUrlstring

exportUrlstring

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/auth/connections/{id}/rotate-secret

Rotate an auth connection secret

Issues a new signing secret, returned once. The previous one keeps verifying for 24 hours, or until revoked.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

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

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections/{id}/rotate-secret" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/rotate-secret', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections/{id}/rotate-secret",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections/{id}/rotate-secret", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/auth/connections/{id}/rotate-secret');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}/rotate-secret')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/auth/connections/{id}/rotate-secret"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("POST", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "provider": "string",
  "secret": "string",
  "previousSecretExpiresAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

providerstringrequired

secretstringrequired

The new secret, shown once. The previous one keeps working until previousSecretExpiresAt.

previousSecretExpiresAtstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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.

DELETEhttps://referalli.com/v1/auth/connections/{id}

Delete an auth connection

Removes the connection; its webhook URL and signed endpoints stop accepting calls. Referrals it filed stay.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

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

Code samples

cURL

curl -X DELETE "https://referalli.com/v1/auth/connections/{id}" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}', {
  method: 'DELETE',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "DELETE",
    "https://referalli.com/v1/auth/connections/{id}",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://referalli.com/v1/auth/connections/{id}", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/auth/connections/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}')
req = Net::HTTP::Delete.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/auth/connections/{id}"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("DELETE", BodyPublishers.noBody())
    .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"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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.

PATCHhttps://referalli.com/v1/auth/connections/{id}

Update an auth connection

Pauses or resumes a connection, renames it, changes autoEnrollUsers or the destination of auto-created links, or (signed-protocol connections) sets signatureVersion: v2 to require request-line signatures, v1+v2 to accept both again.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

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

statusstring

active | paused

namestring

autoEnrollUsersboolean

destinationUrlstring

signatureVersionstring

v1+v2 | v2

{
  "status": "active",
  "name": "string",
  "autoEnrollUsers": true,
  "destinationUrl": "string",
  "signatureVersion": "v1+v2"
}

Code samples

cURL

curl -X PATCH "https://referalli.com/v1/auth/connections/{id}" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"status":"active","name":"string","autoEnrollUsers":true,"destinationUrl":"string","signatureVersion":"v1+v2"}'

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}', {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"status":"active","name":"string","autoEnrollUsers":true,"destinationUrl":"string","signatureVersion":"v1+v2"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "PATCH",
    "https://referalli.com/v1/auth/connections/{id}",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"status": "active", "name": "string", "autoEnrollUsers": True, "destinationUrl": "string", "signatureVersion": "v1+v2"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("PATCH", "https://referalli.com/v1/auth/connections/{id}", strings.NewReader(`{"status":"active","name":"string","autoEnrollUsers":true,"destinationUrl":"string","signatureVersion":"v1+v2"}`))
	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/auth/connections/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"status":"active","name":"string","autoEnrollUsers":true,"destinationUrl":"string","signatureVersion":"v1+v2"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}')
req = Net::HTTP::Patch.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"status":"active","name":"string","autoEnrollUsers":true,"destinationUrl":"string","signatureVersion":"v1+v2"}'
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/auth/connections/{id}"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("PATCH", BodyPublishers.ofString("{\"status\":\"active\",\"name\":\"string\",\"autoEnrollUsers\":true,\"destinationUrl\":\"string\",\"signatureVersion\":\"v1+v2\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "provider": "string",
  "name": "string",
  "status": "active",
  "autoEnrollUsers": true,
  "destinationUrl": "string",
  "signatureVersion": "v1+v2",
  "requiresV2": true
}

Schema

idstringrequired

providerstringrequired

namestringrequired

statusstringrequired

active | paused

autoEnrollUsersboolean

destinationUrlstring

signatureVersionstring

v1+v2 | v2

requiresV2boolean

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/auth/connections/{id}/revoke-previous-secret

Revoke the previous auth secret

Ends the rotation overlap at once: only the newest secret verifies from now on.

Auth: an API key with integrations:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

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

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections/{id}/revoke-previous-secret" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/revoke-previous-secret', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections/{id}/revoke-previous-secret",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections/{id}/revoke-previous-secret", nil)
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/auth/connections/{id}/revoke-previous-secret');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}/revoke-previous-secret')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.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/auth/connections/{id}/revoke-previous-secret"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("POST", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "revoked": true
}

Schema

okbooleanrequired

revokedbooleanrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

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/auth/connections/{id}/signups

Attribute a new user (signed protocol)

The auth platform reports a new user with the referral context captured at sign-up (referral.code, or with cookie consent clickId/anonId) and optional risk signals. The user is attributed (risky sign-ups are held for review), optionally made a partner with their own link, and the answer says why with reason codes. test: true or atlas-test: 1 simulates without storing. Repeating the same user is idempotent. Signed with the connection secret in x-referalli-signature: t=<unix>,v1=…,v2=… (v2 also signs the request line; once a connection has seen v2 it requires it), with a unique x-referalli-id per call. The legacy header names from before the rename are also accepted, for existing integrations. Calls older than 5 minutes, reused ids (409 replay), paused connections (423 connection_paused) and unknown fields (422) are refused.

Auth: a signature (see above); no API key.

Parameters

idstringpathrequired

Request body application/json

customerRefstringrequired

emailstring

emailHashstring

namestring

ipstring

uastring

signedUpAtstringrequired

referralobject

Show child parameters

codestring

clickIdstring

anonIdstring

capturedAtstring

consentstring

granted | not_required = not_required

riskobject

Show child parameters

botScorenumber

disposableEmailboolean

emailVerifiedboolean

selfReferralboolean

velocityinteger

reasonsstring[]

scorenumber

levelstring

low | medium | high

droppedboolean

emailDomainstring

referralCodestring

autoEnrollboolean

testboolean

{
  "customerRef": "string",
  "email": "string",
  "emailHash": "string",
  "name": "string",
  "ip": "string",
  "ua": "string",
  "signedUpAt": "2024-01-01T00:00:00Z",
  "referral": {
    "code": "string",
    "clickId": "string",
    "anonId": "string",
    "capturedAt": "2024-01-01T00:00:00Z",
    "consent": "not_required"
  },
  "risk": {
    "botScore": 0,
    "disposableEmail": true,
    "emailVerified": true,
    "selfReferral": true,
    "velocity": 0,
    "reasons": [
      "string"
    ],
    "score": 0,
    "level": "low",
    "dropped": true
  },
  "emailDomain": "string",
  "referralCode": "string",
  "autoEnroll": true,
  "test": true
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections/{id}/signups" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"string","email":"string","emailHash":"string","name":"string","ip":"string","ua":"string","signedUpAt":"2024-01-01T00:00:00Z","referral":{"code":"string","clickId":"string","anonId":"string","capturedAt":"2024-01-01T00:00:00Z","consent":"not_required"},"risk":{"botScore":0,"disposableEmail":true,"emailVerified":true,"selfReferral":true,"velocity":0,"reasons":["string"],"score":0,"level":"low","dropped":true},"emailDomain":"string","referralCode":"string","autoEnroll":true,"test":true}'

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/signups', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"customerRef":"string","email":"string","emailHash":"string","name":"string","ip":"string","ua":"string","signedUpAt":"2024-01-01T00:00:00Z","referral":{"code":"string","clickId":"string","anonId":"string","capturedAt":"2024-01-01T00:00:00Z","consent":"not_required"},"risk":{"botScore":0,"disposableEmail":true,"emailVerified":true,"selfReferral":true,"velocity":0,"reasons":["string"],"score":0,"level":"low","dropped":true},"emailDomain":"string","referralCode":"string","autoEnroll":true,"test":true}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections/{id}/signups",
    headers={
    "Content-Type": "application/json",
    },
    json={"customerRef": "string", "email": "string", "emailHash": "string", "name": "string", "ip": "string", "ua": "string", "signedUpAt": "2024-01-01T00:00:00Z", "referral": {"code": "string", "clickId": "string", "anonId": "string", "capturedAt": "2024-01-01T00:00:00Z", "consent": "not_required"}, "risk": {"botScore": 0, "disposableEmail": True, "emailVerified": True, "selfReferral": True, "velocity": 0, "reasons": ["string"], "score": 0, "level": "low", "dropped": True}, "emailDomain": "string", "referralCode": "string", "autoEnroll": True, "test": True},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections/{id}/signups", strings.NewReader(`{"customerRef":"string","email":"string","emailHash":"string","name":"string","ip":"string","ua":"string","signedUpAt":"2024-01-01T00:00:00Z","referral":{"code":"string","clickId":"string","anonId":"string","capturedAt":"2024-01-01T00:00:00Z","consent":"not_required"},"risk":{"botScore":0,"disposableEmail":true,"emailVerified":true,"selfReferral":true,"velocity":0,"reasons":["string"],"score":0,"level":"low","dropped":true},"emailDomain":"string","referralCode":"string","autoEnroll":true,"test":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/v1/auth/connections/{id}/signups');
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","email":"string","emailHash":"string","name":"string","ip":"string","ua":"string","signedUpAt":"2024-01-01T00:00:00Z","referral":{"code":"string","clickId":"string","anonId":"string","capturedAt":"2024-01-01T00:00:00Z","consent":"not_required"},"risk":{"botScore":0,"disposableEmail":true,"emailVerified":true,"selfReferral":true,"velocity":0,"reasons":["string"],"score":0,"level":"low","dropped":true},"emailDomain":"string","referralCode":"string","autoEnroll":true,"test":true}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}/signups')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"customerRef":"string","email":"string","emailHash":"string","name":"string","ip":"string","ua":"string","signedUpAt":"2024-01-01T00:00:00Z","referral":{"code":"string","clickId":"string","anonId":"string","capturedAt":"2024-01-01T00:00:00Z","consent":"not_required"},"risk":{"botScore":0,"disposableEmail":true,"emailVerified":true,"selfReferral":true,"velocity":0,"reasons":["string"],"score":0,"level":"low","dropped":true},"emailDomain":"string","referralCode":"string","autoEnroll":true,"test":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/v1/auth/connections/{id}/signups"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"customerRef\":\"string\",\"email\":\"string\",\"emailHash\":\"string\",\"name\":\"string\",\"ip\":\"string\",\"ua\":\"string\",\"signedUpAt\":\"2024-01-01T00:00:00Z\",\"referral\":{\"code\":\"string\",\"clickId\":\"string\",\"anonId\":\"string\",\"capturedAt\":\"2024-01-01T00:00:00Z\",\"consent\":\"not_required\"},\"risk\":{\"botScore\":0,\"disposableEmail\":true,\"emailVerified\":true,\"selfReferral\":true,\"velocity\":0,\"reasons\":[\"string\"],\"score\":0,\"level\":\"low\",\"dropped\":true},\"emailDomain\":\"string\",\"referralCode\":\"string\",\"autoEnroll\":true,\"test\":true}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "test": true,
  "referral": {
    "id": "string",
    "partnerId": "string",
    "partnerExternalRef": "string",
    "matchedVia": "string",
    "status": "string",
    "persisted": true
  },
  "reasoning": {
    "notes": [
      "string"
    ],
    "codes": [
      "consent_missing"
    ]
  },
  "partner": {
    "id": "string",
    "code": "string",
    "link": "string",
    "persisted": true
  }
}

Schema

testboolean

Present on a test signup ("test": true or atlas-test: 1): answered as a real call, nothing stored.

referralobjectrequired

Show child parameters

idstringrequired

partnerIdstringrequired

partnerExternalRefstringrequired

matchedViastringrequired

statusstringrequired

persistedboolean

Test signups only: true when this referral already existed; false when it exists only in this answer.

reasoningobject

Show child parameters

notesstring[]required

English, for people; wording may change.

codesSignupReasonCode[]required

One stable code per distinct reason behind notes, in order.

partnerobject

Show child parameters

idstringrequired

codestringrequired

linkstringrequired

The partner's absolute tracked link (/go/{trackingToken}/{code}), on the org's verified link domain when it has one; null when they have only a coupon.

persistedboolean

Test signups only: true when this partner already existed; false when it exists only in this answer.

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

423 The connection is paused. error.code is one of:

Example

{
  "error": {
    "code": "connection_paused",
    "message": "the merchant paused this auth connection",
    "docs_url": "https://referalli.com/docs/errors-and-limits#connection_paused"
  }
}

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/auth/connections/{id}/erase

Erase a user (signed protocol)

The platform deleted a user or fulfilled an erasure request: the customer's referral data and their partner record are erased. An unknown user succeeds with nothing erased. Signed with the connection secret in x-referalli-signature: t=<unix>,v1=…,v2=… (v2 also signs the request line; once a connection has seen v2 it requires it), with a unique x-referalli-id per call. The legacy header names from before the rename are also accepted, for existing integrations. Calls older than 5 minutes, reused ids (409 replay), paused connections (423 connection_paused) and unknown fields (422) are refused.

Auth: a signature (see above); no API key.

Parameters

idstringpathrequired

Request body application/json

customerRefstringrequired

{
  "customerRef": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections/{id}/erase" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"string"}'

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/erase', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"customerRef":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections/{id}/erase",
    headers={
    "Content-Type": "application/json",
    },
    json={"customerRef": "string"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections/{id}/erase", strings.NewReader(`{"customerRef":"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/v1/auth/connections/{id}/erase');
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"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}/erase')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"customerRef":"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/auth/connections/{id}/erase"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"customerRef\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "erased": true,
  "customer": {
    "customerRef": "string",
    "pseudonym": "string"
  },
  "partner": {
    "partnerId": "string",
    "alreadyForgotten": true
  }
}

Schema

okbooleanrequired

erasedbooleanrequired

False when nothing was filed under the customer (a retry settles cleanly).

customerobjectrequired

Show child parameters

customerRefstringrequired

pseudonymstringrequired

partnerobjectrequired

Show child parameters

partnerIdstringrequired

alreadyForgottenbooleanrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

423 The connection is paused. error.code is one of:

Example

{
  "error": {
    "code": "connection_paused",
    "message": "the merchant paused this auth connection",
    "docs_url": "https://referalli.com/docs/errors-and-limits#connection_paused"
  }
}

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/auth/connections/{id}/export

Export a user (signed protocol)

An access request the platform forwards: everything filed under the customer and their partner record. Signed with the connection secret in x-referalli-signature: t=<unix>,v1=…,v2=… (v2 also signs the request line; once a connection has seen v2 it requires it), with a unique x-referalli-id per call. The legacy header names from before the rename are also accepted, for existing integrations. Calls older than 5 minutes, reused ids (409 replay), paused connections (423 connection_paused) and unknown fields (422) are refused.

Auth: a signature (see above); no API key.

Parameters

idstringpathrequired

customerRefstringqueryrequired

Code samples

cURL

curl -X GET "https://referalli.com/v1/auth/connections/{id}/export?customerRef="

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/export?customerRef=', {
  method: 'GET',
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/auth/connections/{id}/export?customerRef=",
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/auth/connections/{id}/export?customerRef=", 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/auth/connections/{id}/export?customerRef=');
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/auth/connections/{id}/export?customerRef=')
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/auth/connections/{id}/export?customerRef="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "customer": {
    "customerRef": "string",
    "referrals": [
      {}
    ],
    "associations": [
      {}
    ],
    "identityLinks": [
      {}
    ],
    "billingEvents": [
      {}
    ],
    "conversionEvents": [
      {}
    ]
  },
  "partner": {
    "partner": {},
    "enrollments": [
      {}
    ],
    "links": [
      {}
    ],
    "coupons": [
      {}
    ],
    "payoutProfile": {},
    "commissionEvents": [
      {}
    ],
    "payouts": [
      {}
    ]
  }
}

Schema

customerobjectrequired

Show child parameters

customerRefstringrequired

referralsGetOpenapiJsonResponse[]required

associationsGetOpenapiJsonResponse[]required

identityLinksGetOpenapiJsonResponse[]required

billingEventsGetOpenapiJsonResponse[]required

conversionEventsGetOpenapiJsonResponse[]required

partnerPartnerExportrequired

Show child parameters

partnerobjectrequired

enrollmentsGetOpenapiJsonResponse[]required

linksGetOpenapiJsonResponse[]required

couponsGetOpenapiJsonResponse[]required

payoutProfileGetOpenapiJsonResponserequired

commissionEventsGetOpenapiJsonResponse[]required

payoutsGetOpenapiJsonResponse[]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"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

423 The connection is paused. error.code is one of:

Example

{
  "error": {
    "code": "connection_paused",
    "message": "the merchant paused this auth connection",
    "docs_url": "https://referalli.com/docs/errors-and-limits#connection_paused"
  }
}

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/auth/connections/{id}/ping

Test an auth connection (signed protocol)

Proves the secret works: returns the connection, its program and org and the server time, to check clock skew. Signed with the connection secret in x-referalli-signature: t=<unix>,v1=…,v2=… (v2 also signs the request line; once a connection has seen v2 it requires it), with a unique x-referalli-id per call. The legacy header names from before the rename are also accepted, for existing integrations. Calls older than 5 minutes, reused ids (409 replay), paused connections (423 connection_paused) and unknown fields (422) are refused.

Auth: a signature (see above); no API key.

Parameters

idstringpathrequired

Request body application/json

{}

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections/{id}/ping" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/ping', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections/{id}/ping",
    headers={
    "Content-Type": "application/json",
    },
    json={},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections/{id}/ping", strings.NewReader(`{}`))
	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/auth/connections/{id}/ping');
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, '{}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}/ping')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{}'
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/auth/connections/{id}/ping"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "connectionId": "string",
  "programId": "string",
  "orgName": "string",
  "autoEnrollUsers": true,
  "serverTime": "2024-01-01T00:00:00Z"
}

Schema

okbooleanrequired

connectionIdstringrequired

programIdstringrequired

orgNamestringrequired

autoEnrollUsersbooleanrequired

serverTimestringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

423 The connection is paused. error.code is one of:

Example

{
  "error": {
    "code": "connection_paused",
    "message": "the merchant paused this auth connection",
    "docs_url": "https://referalli.com/docs/errors-and-limits#connection_paused"
  }
}

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/auth/connections/{id}/aliases

Change a user's id (signed protocol)

The app stamped or changed a user's id after the sign-up was filed: referrals and identity move from fromCustomerRef to toCustomerRef. Publishes customer.aliased. Signed with the connection secret in x-referalli-signature: t=<unix>,v1=…,v2=… (v2 also signs the request line; once a connection has seen v2 it requires it), with a unique x-referalli-id per call. The legacy header names from before the rename are also accepted, for existing integrations. Calls older than 5 minutes, reused ids (409 replay), paused connections (423 connection_paused) and unknown fields (422) are refused.

Auth: a signature (see above); no API key.

Parameters

idstringpathrequired

Request body application/json

fromCustomerRefstringrequired

toCustomerRefstringrequired

{
  "fromCustomerRef": "string",
  "toCustomerRef": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections/{id}/aliases" \
  -H "Content-Type: application/json" \
  -d '{"fromCustomerRef":"string","toCustomerRef":"string"}'

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/aliases', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"fromCustomerRef":"string","toCustomerRef":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections/{id}/aliases",
    headers={
    "Content-Type": "application/json",
    },
    json={"fromCustomerRef": "string", "toCustomerRef": "string"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections/{id}/aliases", strings.NewReader(`{"fromCustomerRef":"string","toCustomerRef":"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/v1/auth/connections/{id}/aliases');
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, '{"fromCustomerRef":"string","toCustomerRef":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}/aliases')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"fromCustomerRef":"string","toCustomerRef":"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/auth/connections/{id}/aliases"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"fromCustomerRef\":\"string\",\"toCustomerRef\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "customerRef": "string",
  "referralIds": [
    "string"
  ],
  "partnerId": "string",
  "alreadyAliased": true,
  "reprocessedPayments": 0
}

Schema

okbooleanrequired

customerRefstringrequired

referralIdsstring[]required

partnerIdstringrequired

alreadyAliasedbooleanrequired

reprocessedPaymentsintegerrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

423 The connection is paused. error.code is one of:

Example

{
  "error": {
    "code": "connection_paused",
    "message": "the merchant paused this auth connection",
    "docs_url": "https://referalli.com/docs/errors-and-limits#connection_paused"
  }
}

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/auth/connections/{id}/users

Update a user (signed protocol)

The user changed: email and name follow to their partner record, suspended suspends it, deleted erases. Signed with the connection secret in x-referalli-signature: t=<unix>,v1=…,v2=… (v2 also signs the request line; once a connection has seen v2 it requires it), with a unique x-referalli-id per call. The legacy header names from before the rename are also accepted, for existing integrations. Calls older than 5 minutes, reused ids (409 replay), paused connections (423 connection_paused) and unknown fields (422) are refused.

Auth: a signature (see above); no API key.

Parameters

idstringpathrequired

Request body application/json

customerRefstringrequired

emailstring

namestring

statusstring

active | suspended | deleted

{
  "customerRef": "string",
  "email": "string",
  "name": "string",
  "status": "active"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections/{id}/users" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"string","email":"string","name":"string","status":"active"}'

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"customerRef":"string","email":"string","name":"string","status":"active"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections/{id}/users",
    headers={
    "Content-Type": "application/json",
    },
    json={"customerRef": "string", "email": "string", "name": "string", "status": "active"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections/{id}/users", strings.NewReader(`{"customerRef":"string","email":"string","name":"string","status":"active"}`))
	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/auth/connections/{id}/users');
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","email":"string","name":"string","status":"active"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}/users')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"customerRef":"string","email":"string","name":"string","status":"active"}'
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/auth/connections/{id}/users"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"customerRef\":\"string\",\"email\":\"string\",\"name\":\"string\",\"status\":\"active\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "deleted": true,
  "erased": true,
  "customer": {
    "customerRef": "string",
    "pseudonym": "string"
  },
  "partner": {
    "partnerId": "string",
    "alreadyForgotten": true
  },
  "updated": [
    "string"
  ],
  "notes": [
    "string"
  ]
}

Schema

okbooleanrequired

deletedboolean

erasedboolean

customerobject

Show child parameters

customerRefstringrequired

pseudonymstringrequired

partnerobjectrequired

updatedstring[]

notesstring[]

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

423 The connection is paused. error.code is one of:

Example

{
  "error": {
    "code": "connection_paused",
    "message": "the merchant paused this auth connection",
    "docs_url": "https://referalli.com/docs/errors-and-limits#connection_paused"
  }
}

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/auth/connections/{id}/signals

Report a user signal (signed protocol)

A later verdict about a user: email_verified releases a hold for an unverified email, fraud_confirmed or self_referral voids their referral, banned/unbanned follow on their partner record. details is kept as evidence. Signed with the connection secret in x-referalli-signature: t=<unix>,v1=…,v2=… (v2 also signs the request line; once a connection has seen v2 it requires it), with a unique x-referalli-id per call. The legacy header names from before the rename are also accepted, for existing integrations. Calls older than 5 minutes, reused ids (409 replay), paused connections (423 connection_paused) and unknown fields (422) are refused.

Auth: a signature (see above); no API key.

Parameters

idstringpathrequired

Request body application/json

customerRefstringrequired

signalstringrequired

email_verified | banned | unbanned | fraud_confirmed | self_referral

atstring

detailsobject

{
  "customerRef": "string",
  "signal": "email_verified",
  "at": "2024-01-01T00:00:00Z",
  "details": {}
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/auth/connections/{id}/signals" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"string","signal":"email_verified","at":"2024-01-01T00:00:00Z","details":{}}'

TypeScript

const res = await fetch('https://referalli.com/v1/auth/connections/{id}/signals', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"customerRef":"string","signal":"email_verified","at":"2024-01-01T00:00:00Z","details":{}}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/auth/connections/{id}/signals",
    headers={
    "Content-Type": "application/json",
    },
    json={"customerRef": "string", "signal": "email_verified", "at": "2024-01-01T00:00:00Z", "details": {}},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/auth/connections/{id}/signals", strings.NewReader(`{"customerRef":"string","signal":"email_verified","at":"2024-01-01T00:00:00Z","details":{}}`))
	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/auth/connections/{id}/signals');
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","signal":"email_verified","at":"2024-01-01T00:00:00Z","details":{}}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/auth/connections/{id}/signals')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"customerRef":"string","signal":"email_verified","at":"2024-01-01T00:00:00Z","details":{}}'
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/auth/connections/{id}/signals"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"customerRef\":\"string\",\"signal\":\"email_verified\",\"at\":\"2024-01-01T00:00:00Z\",\"details\":{}}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "signal": "email_verified",
  "referrals": [
    {
      "id": "string",
      "status": "string"
    }
  ],
  "reversed": [
    {
      "lineId": "string",
      "amountMinor": 0,
      "currency": "string"
    }
  ],
  "partner": {
    "id": "string",
    "status": "string"
  },
  "notes": [
    "string"
  ]
}

Schema

okbooleanrequired

signalstringrequired

email_verified | banned | unbanned | fraud_confirmed | self_referral

referralsobject[]required

Show child parameters

idstringrequired

statusstringrequired

reversedobject[]required

Show child parameters

lineIdstringrequired

amountMinorintegerrequired

Integer minor units (cents).

currencystringrequired

partnerobjectrequired

Show child parameters

idstringrequired

statusstringrequired

notesstring[]

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

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"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "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.

423 The connection is paused. error.code is one of:

Example

{
  "error": {
    "code": "connection_paused",
    "message": "the merchant paused this auth connection",
    "docs_url": "https://referalli.com/docs/errors-and-limits#connection_paused"
  }
}

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 Oct 23, 2026

Was this page helpful?