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"
}
}
Referrals
Get Referral
Retrieve detailed information about a specific referral
GET
/
api
/
v1
/
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_123abcRequest 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.Was this page helpful?