Get Referral

curl -X GET "https://vantio.app/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"
  }
}

GET

api

referrals

{id}

curl -X GET "https://vantio.app/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

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 "https://vantio.app/api/v1/referrals/ref_123abc" \
  -H "Authorization: Bearer sk_your_secret_key_here"

Response

The API returns a detailed referral object:

string

required

Unique identifier for the referral.

string

required

ID of the impression (QR scan) that led to this referral.

string

required

First name of the referred person.

string

required

Last name of the referred person.

string

required

Email address of the referred person.

string

URL to the profile picture, if available.

string

required

Current status: pending, converted, verified, or rejected.

string

required

ID of the program this referral belongs to.

string

required

ID of the student ambassador who generated this referral.

string

required

ISO 8601 timestamp of when the referral was created.

string

ISO 8601 timestamp of when the referral was verified, if applicable.

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

object

Unauthorized - Invalid or missing API key

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

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(
    `https://vantio.app/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(
          `https://vantio.app/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

Cache referral data - Referral information doesn’t change frequently
Handle 404 errors - Always check if the referral exists
Monitor status changes - Use webhooks or polling to track status updates
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

string

required

Referral ID

Response

Referral details

The response is of type object.

API Documentation

Users

Referrals

Posters

Impressions

Earnings

Overview

Authentication

Path Parameters

Request Example

Response

Response Example

Error Responses

Use Cases

Checking Referral Status

Building Referral Detail View

Best Practices

Rate Limits

Authorizations

Path Parameters

Response

​Overview

​Authentication

​Path Parameters

​Request Example

​Response

​Response Example

​Error Responses

​Use Cases

​Checking Referral Status

​Building Referral Detail View

​Best Practices

​Rate Limits

Authorizations

Path Parameters

Response

Overview

Authentication

Path Parameters

Request Example

Response

Response Example

Error Responses

Use Cases

Checking Referral Status

Building Referral Detail View

Best Practices

Rate Limits