Ready-to-Use Code Examples

Badge API Code Examples

Copy-paste code examples for issuing badges with expiration dates, custom fields, and image uploads. Available in JavaScript, PHP, and Python.

View Code Examples Back to API Docs

1. Basic Badge Issuance

Simple example to issue a badge to a recipient

// Issue a basic badge using fetch API
const issueBadge = async () => {
  const response = await fetch('https://yourdomain.com/api/v1/issue/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      badge_id: 'abc123',              // Your badge ID
      name: 'John Doe',                // Recipient name
      email: 'john@example.com',       // Recipient email
      phone: '+1234567890',            // Optional: Recipient phone
      idempotency_key: 'unique-key-' + Date.now()  // Unique key to prevent duplicates
    })
  });

  const data = await response.json();

  if (data.success) {
    console.log('Badge issued successfully!');
    console.log('Badge URL:', data.publicUrl);
    console.log('Badge ID:', data.IssueId);
  } else {
    console.error('Error:', data.message);
  }
};

issueBadge();

Success Response 

{
  "success": true,
  "IssueId": "xyz789",
  "publicUrl": "https://yourdomain.com/v/xyz789"
}

2. Badge with Expiration Date

Issue badges that expire after a specific date or period

Auto-calculation: If the badge template has expiration settings, the API will automatically calculate the expiration date. You can override it by passing expire_date. 

// Issue badge with custom expiration date
const issueBadgeWithExpiration = async () => {
  // Calculate expiration date (2 years from now)
  const issueDate = new Date();
  const expireDate = new Date(issueDate);
  expireDate.setFullYear(expireDate.getFullYear() + 2);

  // Format as YYYY-MM-DD
  const expireDateString = expireDate.toISOString().split('T')[0];

  const response = await fetch('https://yourdomain.com/api/v1/issue/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      badge_id: 'abc123',
      name: 'John Doe',
      email: 'john@example.com',
      expire_date: expireDateString,  // Override auto-calculation
      idempotency_key: 'unique-key-' + Date.now()
    })
  });

  const data = await response.json();

  if (data.success) {
    console.log('Badge issued with expiration:', expireDateString);
    console.log('Badge URL:', data.publicUrl);
  }
};

issueBadgeWithExpiration();

Auto-Calculation

Don't pass expire_date to use the badge template's expiration settings (e.g., "2 years duration").

Custom Expiration

Pass expire_date in YYYY-MM-DD format to override and set a specific expiration date.

3. Badge with Custom Fields

Add custom data like employee ID, scores, dates, and more

// Issue badge with custom fields
const issueBadgeWithCustomFields = async () => {
  const response = await fetch('https://yourdomain.com/api/v1/issue/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      badge_id: 'abc123',
      name: 'John Doe',
      email: 'john@example.com',
      idempotency_key: 'unique-key-' + Date.now(),

      // Custom fields (defined in badge template)
      metadata: {
        employee_id: 'EMP001',           // Text field
        department: 'Engineering',       // Text field
        score: 95,                       // Number field
        completion_date: '2025-11-10',   // Date field
        training_hours: 40,              // Number field
        instructor_name: 'Jane Smith'    // Text field
      }
    })
  });

  const data = await response.json();

  if (data.success) {
    console.log('Badge issued with custom fields!');
    console.log('Badge URL:', data.publicUrl);
  }
};

issueBadgeWithCustomFields();

Supported Custom Field Types

Text: "John Doe"
Number: 95
Date: "2025-11-10"

4. Custom Fields with Image Upload

Upload images as base64 or URLs - API auto-detects!

Smart Detection: The API automatically detects if you're sending a URL or base64 encoded image. Both work seamlessly! 

// Option 1: Upload image as base64
const uploadImageBase64 = async (fileInput) => {
  const file = fileInput.files[0];

  // Convert file to base64
  const reader = new FileReader();
  reader.readAsDataURL(file);

  reader.onload = async () => {
    const base64Image = reader.result;  // e.g., "data:image/jpeg;base64,/9j/..."

    const response = await fetch('https://yourdomain.com/api/v1/issue/create', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        badge_id: 'abc123',
        name: 'John Doe',
        email: 'john@example.com',
        idempotency_key: 'unique-key-' + Date.now(),
        metadata: {
          employee_id: 'EMP001',
          certificate_photo: base64Image  // Base64 image - auto uploads!
        }
      })
    });

    const data = await response.json();
    if (data.success) {
      console.log('Badge issued with image!');
      console.log('Badge URL:', data.publicUrl);
    }
  };
};

// Option 2: Use pre-uploaded image URL
const uploadImageURL = async () => {
  const response = await fetch('https://yourdomain.com/api/v1/issue/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      badge_id: 'abc123',
      name: 'John Doe',
      email: 'john@example.com',
      idempotency_key: 'unique-key-' + Date.now(),
      metadata: {
        employee_id: 'EMP001',
        certificate_photo: 'https://example.com/photo.jpg'  // Direct URL
      }
    })
  });

  const data = await response.json();
  if (data.success) {
    console.log('Badge issued with image URL!');
  }
};

// Usage with file input
const fileInput = document.getElementById('photoUpload');
uploadImageBase64(fileInput);

Base64 Upload

Single request - image is decoded and uploaded automatically to S3. Max 5MB.

URL Upload

Pass a valid image URL. Image must be publicly accessible. No upload needed.

5. GET Request / Webhook Style

Issue badges using GET requests - perfect for webhooks!

Webhook Friendly: Use GET requests when you need to trigger badge issuance from webhooks, Zapier, or other no-code tools. 

// Issue badge using GET request
const issueBadgeGET = async () => {
  const params = new URLSearchParams({
    badge_id: 'abc123',
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+1234567890',
    expire_date: '2027-11-10',
    idempotency_key: 'unique-key-' + Date.now()
  });

  const url = `https://yourdomain.com/api/v1/issue/create?${params}`;

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  });

  const data = await response.json();

  if (data.success) {
    console.log('Badge issued via GET!');
    console.log('Badge URL:', data.publicUrl);
  }
};

issueBadgeGET();

🔗 Webhooks

Trigger from Zapier, Make.com, or any webhook service without code.

📧 Email Links

Create personalized links in emails that issue badges on click.

🔧 No-Code Tools

Integrate with Airtable, Google Sheets, or any tool that supports webhooks.

Quick Reference

API Endpoint

POST/GET /api/v1/issue/create

Authentication

Bearer YOUR_API_TOKEN

Required Parameters

badge_id

Your badge template ID

name

Recipient full name

idempotency_key

Unique request identifier

Optional Parameters

email
phone
expire_date
metadata
Full API Documentation Back to Developer Page