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
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: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
Unauthorized - Invalid or missing API key
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
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?