Credential Activity Tracking

The Credential Activity system provides unified, event-sourced tracking of all credential issuance and claim lifecycle events. It enables partners to have a clear audit trail and analytics for credentials they've issued.

Overview

When credentials are sent through the LearnCard Network, the system automatically logs activity events that track the full lifecycle:

CREATED → DELIVERED → CLAIMED
              ↓
          EXPIRED / FAILED

Event Types

Event	Description
CREATED	Credential created and sent to inbox (email/phone recipient)
DELIVERED	Credential delivered to profile (profile ID/DID recipient)
CLAIMED	Recipient claimed/accepted the credential
EXPIRED	Credential expired before being claimed
FAILED	Credential delivery failed

Activity Record Structure

Each activity record contains:

interface CredentialActivity {
    id: string;              // Unique event ID
    activityId: string;      // Groups related events for same issuance
    eventType: string;       // CREATED | DELIVERED | CLAIMED | EXPIRED | FAILED
    timestamp: string;       // ISO timestamp
    actorProfileId: string;  // Who triggered the action
    recipientType: string;   // 'profile' | 'email' | 'phone'
    recipientIdentifier: string;
    boostUri?: string;       // Associated boost template
    credentialUri?: string;  // Credential URI (for profile sends)
    inboxCredentialId?: string; // Inbox credential ID (for inbox sends)
    integrationId?: string;  // Integration attribution
    source: string;          // Entry point (see Source Types below)
    metadata?: object;       // Additional context
}

Understanding Activity IDs

The activityId is a key concept that links related events in a credential's lifecycle. Each time a credential is sent, a new unique activityId is generated. When that credential is later claimed, the CLAIMED event shares the same activityId.

Example: Same Boost Sent Multiple Times

Boost "Employee Badge"
├── send() to Alice → activityId: "abc123"
│   ├── DELIVERED (timestamp 1)
│   └── CLAIMED (timestamp 2) ← same activityId "abc123"
│
├── send() to Bob → activityId: "def456"  
│   ├── DELIVERED (timestamp 3)
│   └── CLAIMED (timestamp 4) ← same activityId "def456"
│
└── send() to Alice (again) → activityId: "ghi789"
    └── DELIVERED (timestamp 5) ← different activityId even for same recipient

Key points:

• activityId tracks a single issuance lifecycle, not a boost or recipient

• Same boost sent twice = two different activityIds

• Same recipient receiving twice = two different activityIds

• The boostUri field links activities to the boost template for aggregate stats

Source Types

The source field indicates how the credential was issued:

Source	Description
send	Via the unified send() route
sendBoost	Via the sendBoost route
sendCredential	Via the sendCredential route
inbox	Claimed from Universal Inbox
claim	Profile-to-profile credential acceptance
claimLink	Claimed via a claim link (combined send+claim)
contract	Issued via ConsentFlow contract
acceptCredential	Credential accepted by recipient

API Endpoints

Get My Activities

Retrieve a paginated list of credential activities for the authenticated profile.

GET /activity/credentials

Query Parameters:

• limit (number, default: 25) - Max results per page

• cursor (string) - Pagination cursor

• boostUri (string) - Filter by boost template

• eventType (string) - Filter by event type

• integrationId (string) - Filter by integration

Response:

{
    "records": [
        {
            "id": "abc123",
            "activityId": "xyz789",
            "eventType": "DELIVERED",
            "timestamp": "2024-01-15T10:30:00Z",
            "recipientType": "profile",
            "recipientIdentifier": "alice",
            "boostUri": "lc:network:example.com/trpc:boost:123",
            "boost": {
                "id": "123",
                "name": "Achievement Badge",
                "category": "Achievement"
            },
            "recipientProfile": {
                "profileId": "alice",
                "displayName": "Alice Smith"
            }
        }
    ],
    "hasMore": true,
    "cursor": "2024-01-15T10:30:00Z"
}

Get Activity Stats

Retrieve aggregated statistics for credential activities.

GET /activity/credentials/stats

Query Parameters:

• boostUris (string[]) - Filter by boost templates

• integrationId (string) - Filter by integration

Response:

{
    "total": 150,
    "created": 50,
    "delivered": 100,
    "claimed": 75,
    "expired": 5,
    "failed": 2,
    "claimRate": 75.0
}

Get Activity by ID

Retrieve details of a specific activity by its activity ID.

GET /activity/credentials/{activityId}

Get Activity Chain

Retrieve all events in an activity chain by activityId. Returns events ordered chronologically (oldest first) to show the full lifecycle of a credential issuance.

GET /activity/credentials/{activityId}/chain

Response:

[
    {
        "id": "event-1",
        "activityId": "xyz789",
        "eventType": "DELIVERED",
        "timestamp": "2024-01-15T10:30:00Z",
        "source": "send",
        ...
    },
    {
        "id": "event-2",
        "activityId": "xyz789",
        "eventType": "CLAIMED",
        "timestamp": "2024-01-15T11:45:00Z",
        "source": "acceptCredential",
        ...
    }
]

This is useful for tracking the complete lifecycle of a single credential issuance from delivery through claim.

Usage Examples

JavaScript/TypeScript

// Get recent activity
const activity = await learnCard.invoke.getMyActivities({
    limit: 10,
});

console.log(`Total activities: ${activity.records.length}`);

// Get stats for a specific boost
const stats = await learnCard.invoke.getActivityStats({
    boostUris: ['lc:network:example.com/trpc:boost:123'],
});

console.log(`Claim rate: ${stats.claimRate}%`);

Filtering by Event Type

// Get only claimed credentials
const claimed = await learnCard.invoke.getMyActivities({
    eventType: 'CLAIMED',
    limit: 50,
});

Best Practices

1. Use activityId to track lifecycle - Related events share the same activityId, making it easy to track a credential from send to claim.

2. Poll with timestamps - When polling for new activity, use the cursor parameter to efficiently fetch only new events.

3. Filter by boost for template-specific analytics - Use boostUri to get stats for specific credential templates.

4. Monitor claim rates - The claimRate in stats helps identify which credentials are being claimed and which may need follow-up.

Integration with Notifications

Activity events are separate from the notification system. While notifications push real-time updates to recipients, activity records provide a persistent audit trail for issuers.

For real-time updates, consider using webhooks configured during credential issuance.