Skip to main content
GET
/
api
/
v1
/
referrals
/
{id}
curl -X GET "http://localhost:3000/api/v1/referrals/ref_123abc" \
  -H "Authorization: Bearer sk_your_secret_key_here"

{
  "id": "ref_123abc",
  "impression_id": "imp_456def",
  "first_name": "Alice",
  "last_name": "Johnson",
  "email": "alice.johnson@example.com",
  "profile_picture": "https://example.com/profiles/alice.jpg",
  "status": "converted",
  "program_id": "prog_123abc",
  "student_id": "user_123abc",
  "created_at": "2024-01-15T10:30:00Z",
  "verified_at": "2024-01-16T14:20:00Z",
  "metadata": {
    "source": "poster_qr_code",
    "location": "campus_center"
  }
}
Retrieve detailed information about a specific referral by its unique ID. Use this endpoint to fetch complete referral details including status, associated impression, and metadata.

​
Overview

The Get Referral endpoint returns comprehensive information about a single referral. This is useful for:
  • Displaying referral details in dashboards
  • Checking referral status before processing payments
  • Viewing referral information for customer support
  • Building referral detail pages

​
Authentication

This endpoint requires authentication using a Bearer token in the Authorization header: 
Authorization: Bearer sk_your_secret_key_here

​
Path Parameters

​
id
string
required
The unique identifier of the referral you want to retrieve. This ID is returned when you create a referral or list referrals.Example: ref_123abc

​
Request Example

curl -X GET "http://localhost:3000/api/v1/referrals/ref_123abc" \
  -H "Authorization: Bearer sk_your_secret_key_here"

​
Response

The API returns a detailed referral object:
​
id
string
required
Unique identifier for the referral.
​
impression_id
string
required
ID of the impression (QR scan) that led to this referral.
​
first_name
string
required
First name of the referred person.
​
last_name
string
required
Last name of the referred person.
​
email
string
required
Email address of the referred person.
​
profile_picture
string
URL to the profile picture, if available.
​
status
string
required
Current status: pending, converted, verified, or rejected.
​
program_id
string
required
ID of the program this referral belongs to.
​
student_id
string
required
ID of the student ambassador who generated this referral.
​
created_at
string
required
ISO 8601 timestamp of when the referral was created.
​
verified_at
string
ISO 8601 timestamp of when the referral was verified, if applicable.
​
metadata
object
Additional metadata associated with the referral.

​
Response Example

{
  "id": "ref_123abc",
  "impression_id": "imp_456def",
  "first_name": "Alice",
  "last_name": "Johnson",
  "email": "alice.johnson@example.com",
  "profile_picture": "https://example.com/profiles/alice.jpg",
  "status": "converted",
  "program_id": "prog_123abc",
  "student_id": "user_123abc",
  "created_at": "2024-01-15T10:30:00Z",
  "verified_at": "2024-01-16T14:20:00Z",
  "metadata": {
    "source": "poster_qr_code",
    "location": "campus_center"
  }
}

​
Error Responses

​
401
object
Unauthorized - Invalid or missing API key
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
​
404
object
Not Found - The referral with the specified ID does not exist
{
  "error": "Not Found",
  "message": "Referral not found"
}

​
Use Cases

​
Checking Referral Status

Before processing a payment or commission, verify the referral status: 
async function checkReferralStatus(referralId) {
  const response = await fetch(
    `http://localhost:3000/api/v1/referrals/${referralId}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  if (response.status === 404) {
    throw new Error('Referral not found');
  }
  
  const referral = await response.json();
  return referral.status; // 'pending', 'converted', 'verified', or 'rejected'
}

​
Building Referral Detail View

Display complete referral information: 
async function ReferralDetail({ referralId }) {
  const [referral, setReferral] = useState(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    async function fetchReferral() {
      try {
        const response = await fetch(
          `http://localhost:3000/api/v1/referrals/${referralId}`,
          {
            headers: {
              'Authorization': `Bearer ${API_KEY}`
            }
          }
        );
        
        if (response.ok) {
          const data = await response.json();
          setReferral(data);
        }
      } catch (error) {
        console.error('Error:', error);
      } finally {
        setLoading(false);
      }
    }
    
    fetchReferral();
  }, [referralId]);
  
  if (loading) return <div>Loading...</div>;
  if (!referral) return <div>Referral not found</div>;
  
  return (
    <div>
      <h1>{referral.first_name} {referral.last_name}</h1>
      <p>Email: {referral.email}</p>
      <p>Status: {referral.status}</p>
      <p>Created: {new Date(referral.created_at).toLocaleDateString()}</p>
    </div>
  );
}

​
Best Practices

  1. Cache referral data - Referral information doesn’t change frequently
  2. Handle 404 errors - Always check if the referral exists
  3. Monitor status changes - Use webhooks or polling to track status updates
  4. Validate referral IDs - Ensure the ID format is correct before making requests

​
Rate Limits

This endpoint is subject to rate limiting. Check response headers for rate limit information.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string
required

Referral ID

Response

Referral details

The response is of type object.