Referrals
Create referral invite
Issue a sign-up link for one of your customers.
The link opens the Nxos sign-up with the customer’s email filled in and locked: the form does not let it change, and the server refuses a sign-up with any other email, Google sign-up included. The customer still confirms the address through Nxos’s confirmation email. Once they sign up, their organization is attributed to you as its referrer.
Calling again for the same email while the invite is pending returns the same link with a renewed expiry, so you can request it each time you send the customer to Nxos. Referrals are switched on for your organization on the first call if they are not already.
POST
/
v1
/
referral-invites
cURL
curl --request POST \
--url https://api.nxos.io/v1/referral-invites \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "<string>"
}
'import requests
url = "https://api.nxos.io/v1/referral-invites"
payload = { "email": "<string>" }
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({email: '<string>'})
};
fetch('https://api.nxos.io/v1/referral-invites', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nxos.io/v1/referral-invites",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nxos.io/v1/referral-invites"
payload := strings.NewReader("{\n \"email\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nxos.io/v1/referral-invites")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nxos.io/v1/referral-invites")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "referral_invite",
"referralInviteId": "refinv_3c1f0e8a9b2d4c6e8f0a1b2c3d4e5f60",
"email": "[email protected]",
"url": "https://app.nxos.io/r/k7x2m9qp",
"expiresAt": "2027-01-04T14:30:00.000Z",
"createdAt": "2026-10-06T14:30:00.000Z"
}{
"error": {
"code": "missing_api_key",
"message": "No Authorization header provided.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "forbidden",
"message": "Your organization is not enabled for this action.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "quote_expired",
"message": "The quote has expired.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "validation_error",
"message": "Request body failed validation.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected server error occurred.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}Headers
Bearer token. Format: Bearer <api_key>
Unique key per logical operation. UUID v4 recommended. Max 255 characters.
Body
application/json
Request body for POST /v1/referral-invites.
Email address of the customer you are sending to Nxos. Only this email can sign up with the link.
Response
The request has succeeded.
A sign-up link for one customer, locked to the email it was issued for.
Object type. Always referral_invite.
Available options:
referral_invite Unique identifier of the invite.
The email the link is locked to.
Sign-up link to send the customer to. The email is pre-filled and cannot be changed; the customer confirms it by email, and the new organization is attributed to you as its referrer.
ISO 8601 timestamp after which the link no longer works. Requesting the link again for the same email renews it.
ISO 8601 timestamp of when the invite was first issued.
⌘I
cURL
curl --request POST \
--url https://api.nxos.io/v1/referral-invites \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "<string>"
}
'import requests
url = "https://api.nxos.io/v1/referral-invites"
payload = { "email": "<string>" }
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({email: '<string>'})
};
fetch('https://api.nxos.io/v1/referral-invites', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nxos.io/v1/referral-invites",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nxos.io/v1/referral-invites"
payload := strings.NewReader("{\n \"email\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nxos.io/v1/referral-invites")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nxos.io/v1/referral-invites")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "referral_invite",
"referralInviteId": "refinv_3c1f0e8a9b2d4c6e8f0a1b2c3d4e5f60",
"email": "[email protected]",
"url": "https://app.nxos.io/r/k7x2m9qp",
"expiresAt": "2027-01-04T14:30:00.000Z",
"createdAt": "2026-10-06T14:30:00.000Z"
}{
"error": {
"code": "missing_api_key",
"message": "No Authorization header provided.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "forbidden",
"message": "Your organization is not enabled for this action.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "quote_expired",
"message": "The quote has expired.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "validation_error",
"message": "Request body failed validation.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected server error occurred.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}