Developer API

Acheevable API

Integrate Acheevments into your platform with our simple REST API. Display verified credentials anywhere.

Quick Start

Get up and running in minutes

Generate an API key from your Program Settings
Include the key in your requests as a Bearer token
Start fetching Acheevments for your users

Example Request:

curl -X GET "https://hrxvsnmwkgtskguzxmbs.supabase.co/functions/v1/api/acheevments?email=user@example.com" \
  -H "Authorization: Bearer ach_live_your_api_key_here"

API Base URL

All API requests should be made to this base URL

https://hrxvsnmwkgtskguzxmbs.supabase.co/functions/v1/api

Authentication

All API requests (except verification) require authentication using an API key. Include your key in the Authorization header.

Authorization: Bearer ach_live_xxxxxxxxxxxxxxxxx

API keys are scoped per Program

Each Program has its own API key. Responses include both organization and program details, with organization-level branding (logos, icons) taking precedence.

Keep your API keys secure

Never expose API keys in client-side code. Store them securely on your server.

API Endpoints

Base URL: https://hrxvsnmwkgtskguzxmbs.supabase.co/functions/v1/api

GET

/acheevments

Fetch Acheevments for a user by email or acheever ID. Returns only Acheevments from your program.

Query Parameters

emailUser's email address

acheever_idUser's Acheever ID — supports both short format (ACH-XXXXXX) and UUID

Example Response

{
  "success": true,
  "data": {
    "acheevments": [
      {
        "id": "uuid",
        "serial_number": "ACH-ABCD-1234",
        "issue_date": "2025-01-15T00:00:00Z",
        "valid_through": "2026-01-15T00:00:00Z",
        "is_expired": false,
        "validity_status": "active",
        "verification_url": "https://acheevable.lovable.app/verify/ACH-ABCD-1234",
        "og_image_url": "https://...",
        "recipient_name": "Jane Doe",
        "acheevable": {
          "id": "uuid",
          "title": "MIRROR Practitioner",
          "description": "...",
          "credential_type": "certificate",
          "category": "Leadership",
          "is_renewable": true
        },
        "capacities": ["Systems Thinking", "Sensemaking"],
        "program": {
          "id": "uuid",
          "name": "MIRROR"
        },
        "organization": {
          "id": "uuid",
          "name": "The Bureau of Creative Intelligence",
          "logo_url": "https://...",
          "icon_url": "https://..."
        }
      }
    ]
  },
  "meta": {
    "total": 1,
    "timestamp": "2025-01-15T12:00:00Z"
  }
}

Credential Validity

Understanding expiration and renewal fields

Acheevments can have expiration dates. The API provides several fields to help you track credential validity.

Validity Fields

valid_throughISO 8601 timestamp when the credential expires, or null if no expiration

is_expiredBoolean indicating if the credential has passed its expiration date

validity_statusOne of: "active", "expiring_soon", "expired", or null

is_renewableBoolean on the Acheevable indicating if renewal requests are allowed

Status Logic

"expiring_soon" triggers when a credential is within 30 days of its valid_through date. Credentials without expiration dates return null for both valid_through and validity_status.

Error Handling

The API returns consistent error responses with helpful messages.

{
  "success": false,
  "error": "Invalid API key"
}

HTTP Status Codes

200

Success

400

Bad request (missing parameters)

401

Unauthorized (invalid or missing API key)

404

Resource not found

500

Server error

Integration Example

Display Acheevments in your application

// Fetch user's Acheevments
async function getUserAcheevments(email) {
  const response = await fetch(
    `https://hrxvsnmwkgtskguzxmbs.supabase.co/functions/v1/api/acheevments?email=${encodeURIComponent(email)}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.ACHEEVABLE_API_KEY}`
      }
    }
  );
  
  const { data } = await response.json();
  return data.acheevments;
}

// Display badges and check validity
const acheevments = await getUserAcheevments('user@example.com');

acheevments.forEach(acheevment => {
  console.log(acheevment.acheevable.title);
  console.log(acheevment.validity_status); // "active", "expiring_soon", "expired", or null
  
  if (acheevment.is_expired) {
    console.log("This credential has expired");
  } else if (acheevment.validity_status === "expiring_soon") {
    console.log(`Expires on ${acheevment.valid_through}`);
  }
});

Need Help?

If you have questions or run into issues, we're here to help.

Contact Support