curl -X POST "https://vantio.app/api/v1/referrals" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"impression_id": "imp_123abc",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"profile_picture": "https://example.com/profiles/john-doe.jpg",
"metadata": {
"source": "poster_qr_code",
"location": "campus_center"
},
"idempotency_key": "ref_20240115_123456"
}'
{
"id": "ref_789ghi",
"impression_id": "imp_123abc",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"profile_picture": "https://example.com/profiles/john-doe.jpg",
"status": "pending",
"program_id": "prog_123abc",
"student_id": "user_123abc",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"source": "poster_qr_code",
"location": "campus_center"
}
}
Referrals
Create Referral
Create a new referral when someone signs up via a referral link
POST
/
api
/
v1
/
referrals
curl -X POST "https://vantio.app/api/v1/referrals" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"impression_id": "imp_123abc",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"profile_picture": "https://example.com/profiles/john-doe.jpg",
"metadata": {
"source": "poster_qr_code",
"location": "campus_center"
},
"idempotency_key": "ref_20240115_123456"
}'
{
"id": "ref_789ghi",
"impression_id": "imp_123abc",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"profile_picture": "https://example.com/profiles/john-doe.jpg",
"status": "pending",
"program_id": "prog_123abc",
"student_id": "user_123abc",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"source": "poster_qr_code",
"location": "campus_center"
}
}
Create a new referral when someone signs up via a referral link. This endpoint is typically called when a user completes signup after scanning a QR code from an ambassador poster.
Overview
The Create Referral endpoint allows you to register a new referral signup in your system. This is a critical endpoint that links:- The impression (QR scan) that initiated the referral
- The person who signed up (referral)
- The student ambassador who generated the referral
- The program the referral belongs to
- Register new signups from referral links
- Track the conversion funnel from QR scan to signup
- Associate referrals with their originating impressions
- Enable commission tracking for ambassadors
Authentication
This endpoint requires authentication using a Bearer token in the Authorization header:Authorization: Bearer sk_your_secret_key_here
Request Body
Required. The ID of the impression (QR scan) that led to this referral. This links the referral back to the original QR code scan and poster placement.Example:
imp_123abcNote: The impression must exist in your system before creating a referral.Required. Email address of the referred person. This should be a valid email address and is used for communication and verification.Example:
john.doe@example.comOptional URL to the profile picture of the referred person. This can be used to display avatars in dashboards.Example:
https://example.com/profiles/john-doe.jpgOptional additional metadata about the referral. Use this to store custom information like signup source, marketing campaign, or other relevant data.Example:
{
"source": "poster_qr_code",
"location": "campus_center",
"campaign": "spring_2024"
}
Optional unique key for idempotent requests. If you send the same
idempotency_key within a short time window, the API will return the same referral instead of creating a duplicate. This is useful for retry logic.Example: idemp_20240115_123456Best Practice: Use a combination of timestamp and unique identifier to ensure uniqueness.Request Example
curl -X POST "https://vantio.app/api/v1/referrals" \
-H "Authorization: Bearer sk_your_secret_key_here" \
-H "Content-Type: application/json" \
-d '{
"impression_id": "imp_123abc",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"profile_picture": "https://example.com/profiles/john-doe.jpg",
"metadata": {
"source": "poster_qr_code",
"location": "campus_center"
},
"idempotency_key": "ref_20240115_123456"
}'
Response
On success, the API returns the created referral object:Response Example
{
"id": "ref_789ghi",
"impression_id": "imp_123abc",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"profile_picture": "https://example.com/profiles/john-doe.jpg",
"status": "pending",
"program_id": "prog_123abc",
"student_id": "user_123abc",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {
"source": "poster_qr_code",
"location": "campus_center"
}
}
Error Responses
Bad Request - Invalid request dataCommon causes:
{
"error": "Bad Request",
"message": "Missing required field: impression_id"
}
- Missing required fields
- Invalid email format
- Invalid impression_id (impression doesn’t exist)
Unauthorized - Invalid or missing API key
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
Use Cases
Handling Signup Webhooks
When a user signs up via a referral link, create the referral:async function handleSignupWebhook(signupData, impressionId) {
try {
const response = await fetch('https://vantio.app/api/v1/referrals', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
impression_id: impressionId,
first_name: signupData.firstName,
last_name: signupData.lastName,
email: signupData.email,
profile_picture: signupData.profilePicture,
metadata: {
source: 'web_signup',
signup_method: 'email'
},
idempotency_key: `signup_${signupData.userId}_${Date.now()}`
})
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message);
}
const referral = await response.json();
console.log('Referral created:', referral.id);
return referral;
} catch (error) {
console.error('Error creating referral:', error);
throw error;
}
}
Idempotent Referral Creation
Use idempotency keys to prevent duplicate referrals:async function createReferralSafely(referralData, userId) {
const idempotencyKey = `ref_${userId}_${referralData.impression_id}`;
const response = await fetch('https://vantio.app/api/v1/referrals', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
...referralData,
idempotency_key: idempotencyKey
})
});
// If the referral already exists (idempotent), the API returns the existing one
return await response.json();
}
Batch Referral Creation
Create multiple referrals in sequence:async function createReferralsBatch(referralsData) {
const results = [];
for (const referralData of referralsData) {
try {
const referral = await createReferralSafely(referralData, referralData.userId);
results.push({ success: true, referral });
} catch (error) {
results.push({ success: false, error: error.message });
}
}
return results;
}
Best Practices
- Always use idempotency keys - Prevents duplicate referrals if your request is retried
- Validate impression_id - Ensure the impression exists before creating the referral
- Store metadata - Use the metadata field to track useful information for analytics
- Handle errors gracefully - Check for 400 errors and provide user-friendly messages
- Verify email format - Validate email addresses before sending to the API
- Link to impressions - Always provide a valid
impression_idto maintain the referral chain
Workflow
The typical referral creation workflow:- User scans QR code → Impression created
- User clicks through and signs up → Referral created (this endpoint)
- User makes a purchase → Earning created (see Earnings API)
- Referral status updated to
converted
Rate Limits
This endpoint is subject to rate limiting. Check response headers for rate limit information.Authorizations
Body
application/json
Response
Referral created successfully
Was this page helpful?