Update Referral

Update an existing referral’s information. Use this endpoint to change referral status, update contact information, or modify metadata.

Overview

The Update Referral endpoint allows you to modify referral information after it has been created. Common use cases include:

Updating referral status (e.g., from pending to converted)
Correcting contact information
Adding verification timestamps
Updating metadata
Marking referrals as verified or rejected

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 update.Example: ref_123abc

Request Body

All fields in the request body are optional. Only include the fields you want to update.

first_name

string

Update the first name of the referred person.Example: John

last_name

string

Update the last name of the referred person.Example: Doe

string

Update the email address of the referred person.Example: john.doe@example.com

profile_picture

string

Update the URL to the profile picture.Example: https://example.com/profiles/john-doe.jpg

status

string

Update the referral status. Valid values are:

pending - Referral created but not yet converted
converted - Referral has converted (made a purchase/subscription)
verified - Referral has been verified
rejected - Referral was rejected

Example: converted

verified_at

string

ISO 8601 timestamp of when the referral was verified. Typically set when status changes to verified.Example: 2024-01-16T14:20:00Z

metadata

object

Update additional metadata. This will merge with existing metadata or replace it depending on your API configuration.Example:

{
  "source": "poster_qr_code",
  "location": "campus_center",
  "notes": "Verified by admin"
}

Request Example

# Update referral status to converted
curl -X PUT "http://localhost:3000/api/v1/referrals/ref_123abc" \
  -H "Authorization: Bearer sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "converted"
  }'

# Update multiple fields
curl -X PUT "http://localhost:3000/api/v1/referrals/ref_123abc" \
  -H "Authorization: Bearer sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "verified",
    "verified_at": "2024-01-16T14:20:00Z",
    "metadata": {
      "verified_by": "admin_123",
      "verification_notes": "Manual verification completed"
    }
  }'

Response

On success, the API returns the updated referral object:

string

required

Unique identifier for the referral.

impression_id

string

required

ID of the impression that led to this referral.

first_name

string

required

Updated first name (if provided).

last_name

string

required

Updated last name (if provided).

string

required

Updated email (if provided).

status

string

required

Updated status (if provided).

verified_at

string

Updated verification timestamp (if provided).

updated_at

string

required

ISO 8601 timestamp of when the referral was last updated.

Response Example

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

Error Responses

400

object

Bad Request - Invalid request data

{
  "error": "Bad Request",
  "message": "Invalid status value. Must be one of: pending, converted, verified, rejected"
}

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

Marking Referral as Converted

When a referred customer makes a purchase, update the referral status:

async function markReferralAsConverted(referralId) {
  const response = await fetch(
    `http://localhost:3000/api/v1/referrals/${referralId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        status: 'converted'
      })
    }
  );
  
  if (!response.ok) {
    throw new Error('Failed to update referral');
  }
  
  return await response.json();
}

Verifying a Referral

Mark a referral as verified with a timestamp:

async function verifyReferral(referralId, verifiedBy) {
  const response = await fetch(
    `http://localhost:3000/api/v1/referrals/${referralId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        status: 'verified',
        verified_at: new Date().toISOString(),
        metadata: {
          verified_by: verifiedBy,
          verification_date: new Date().toISOString()
        }
      })
    }
  );
  
  return await response.json();
}

Rejecting Invalid Referrals

Mark a referral as rejected if it doesn’t meet criteria:

async function rejectReferral(referralId, reason) {
  const response = await fetch(
    `http://localhost:3000/api/v1/referrals/${referralId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        status: 'rejected',
        metadata: {
          rejection_reason: reason,
          rejected_at: new Date().toISOString()
        }
      })
    }
  );
  
  return await response.json();
}

Updating Contact Information

Correct or update referral contact details:

async function updateReferralContact(referralId, updates) {
  const response = await fetch(
    `http://localhost:3000/api/v1/referrals/${referralId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        first_name: updates.firstName,
        last_name: updates.lastName,
        email: updates.email,
        profile_picture: updates.profilePicture
      })
    }
  );
  
  return await response.json();
}

Best Practices

Update status carefully - Status changes should reflect actual business events
Set verified_at when verifying - Always include a timestamp when marking as verified
Use metadata for context - Store additional context in metadata rather than status alone
Validate status values - Ensure status values are valid before sending
Handle 404 errors - Check if referral exists before updating
Track who made changes - Include admin/user IDs in metadata when updating

Status Workflow

Typical referral status progression:

pending → Created but not yet converted
converted → Referred customer made a purchase
verified → Conversion verified by admin
rejected → Referral doesn’t meet criteria (can happen at any stage)

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

Body

application/json

first_name

string

last_name

string

profile_picture

string

status

enum<string>

Available options:

pending,

converted,

verified,

rejected

verified_at

string<date-time>

metadata

object

Response

Referral updated successfully

API Documentation

Users

Referrals

Posters

Impressions

Earnings

Update Referral

Overview

Authentication

Path Parameters

Request Body

Request Example

Response

Response Example

Error Responses

Use Cases

Marking Referral as Converted

Verifying a Referral

Rejecting Invalid Referrals

Updating Contact Information

Best Practices

Status Workflow

Rate Limits

Authorizations

Path Parameters

Body

Response

API Documentation

Users

Referrals

Posters

Impressions

Earnings

​Overview

​Authentication

​Path Parameters

​Request Body

​Request Example

​Response

​Response Example

​Error Responses

​Use Cases

​Marking Referral as Converted

​Verifying a Referral

​Rejecting Invalid Referrals

​Updating Contact Information

​Best Practices

​Status Workflow

​Rate Limits

Authorizations

Path Parameters

Body

Response

Overview

Authentication

Path Parameters

Request Body

Request Example

Response

Response Example

Error Responses

Use Cases

Marking Referral as Converted

Verifying a Referral

Rejecting Invalid Referrals

Updating Contact Information

Best Practices

Status Workflow

Rate Limits