Qualify Referral

POST

referrals

{id}

qualify

Mark a referral as qualified

curl --request POST \
  --url https://billing.example.com/v1/referrals/{id}/qualify \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/referrals/{id}/qualify', 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://billing.example.com/v1/referrals/{id}/qualify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://billing.example.com/v1/referrals/{id}/qualify"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/referrals/{id}/qualify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "referrer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "referred_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "code": "<string>",
    "status": "pending",
    "reward_amount": 123,
    "currency": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "qualified_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the referral to qualify (e.g. `ref_Kp8mN2xLvQ`).

This endpoint marks a referral as qualified, indicating that the referred customer has met the criteria for the referrer to receive their reward. No request body is required.

Example Request

curl -X POST https://api.recurso.dev/v1/referrals/ref_Kp8mN2xLvQ/qualify \
  -H "Authorization: Bearer rsk_live_7f3a9b2c1d4e8f0a"

Response

Returns the updated referral object with status set to qualified.

{
  "id": "ref_Kp8mN2xLvQ",
  "referrer_id": "d4e5f6a7-b8c9-4d0e-a1f2-b3c4d5e6f7a8",
  "referred_id": "f7a8b9c0-d1e2-4f3a-b4c5-d6e7f8a9b0c1",
  "reward_amount": 1000,
  "currency": "USD",
  "status": "qualified",
  "reward_credited": false,
  "created_at": "2026-05-10T09:30:00Z",
  "qualified_at": "2026-06-23T17:00:00Z",
  "completed_at": null
}

Notes

Only referrals with pending status can be qualified. Attempting to qualify a referral that is already qualified, completed, or expired returns a 422 error.
Qualifying a referral does not automatically credit the reward. The reward is credited once the referral transitions to completed status.
Use this endpoint to manually approve referrals when you have custom qualification criteria beyond the default first-payment trigger.

If your referral program uses automatic qualification, referrals transition to qualified automatically when the referred customer completes their first payment. This endpoint is only needed for manual approval workflows.

Authorizations

Authorization

string

header

required

Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.

Path Parameters

string<uuid>

required

Response

Qualified referral.

data

object

Show child attributes

Mark a referral as qualified

curl --request POST \
  --url https://billing.example.com/v1/referrals/{id}/qualify \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/referrals/{id}/qualify', 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://billing.example.com/v1/referrals/{id}/qualify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://billing.example.com/v1/referrals/{id}/qualify"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/referrals/{id}/qualify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "referrer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "referred_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "code": "<string>",
    "status": "pending",
    "reward_amount": 123,
    "currency": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "qualified_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Path Parameters

Example Request

Response

Notes

Authorizations

Path Parameters

Response

​Path Parameters

​Example Request

​Response

​Notes

Authorizations

Path Parameters

Response

Path Parameters

Example Request

Response

Notes