Widget Platform
For Developers

Build on Aiffinity

Add rich, data-driven widget cards directly into Aiffinity users' feeds. Connect your platform's live data to the people who matter most to your users.

Create account → I have an account →
Overview

What are Widgets?

Widgets are structured data cards rendered natively inside the Aiffinity app. When a user connects your platform, you push data through the Widget API and it appears in their personal feed — beautifully formatted, always up to date.

1

Register

Declare your widget ID, connector, component types, and domain in the Developer Portal.

2

Verify domain

Add a DNS TXT record to prove ownership of your domain. Widgets go live after verification.

3

User connects

When a user links your connector in Aiffinity, you receive a user_connected webhook with their opaque partner_user_id.

4

Push data

POST to /v1/partners/widget-data/:partner_user_id with your payload. The widget appears instantly.

Privacy

Partner User IDs

Aiffinity never exposes real user IDs to partners. Instead, each user-partner pair is assigned a stable, opaque partner_user_id derived via HMAC-SHA256.

How it works: When a user connects your app, Aiffinity fires a POST to your connect_webhook_url containing partner_user_id, widget_id, and a timestamp. Store this ID — it's how you identify the user in all future push calls. 
{
  "event": "user_connected",
  "partner_user_id": "a3f2c91b…",   // stable, opaque — not a real Aiffinity user ID
  "widget_id": "my-widget",
  "timestamp": "2026-03-21T12:00:00Z"
}
Authentication

API Keys

All partner API calls are authenticated with an x-partner-key header. Keys are SHA-256 hashed server-side — the raw value is shown exactly once at creation and never stored.

curl https://api.aiffinity.me/v1/partners/widgets \
  -H "x-partner-key: YOUR_API_KEY"

Rotate your key at any time from the API Keys page. The old key is invalidated immediately.

API Reference

Endpoints

Base URL: https://api.aiffinity.me

MethodPathDescription
GET /v1/partners/widgets
List your registered widgets
POST /v1/partners/widgets
Register a new widget
PATCH /v1/partners/widgets/:widget_id
Update widget manifest (name, webhook URL, accent color, etc.)
POST /v1/partners/verify-domain
Trigger DNS TXT record verification
POST /v1/partners/widget-data/:partner_user_id
Push widget data for a user
POST /v1/partners/api-keys
Rotate your API key
 
// Example: push hero_card widget data
curl -X POST https://api.aiffinity.me/v1/partners/widget-data/PARTNER_USER_ID \
  -H "x-partner-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_id": "my-widget",
    "payload": {
      "component": "hero_card",
      "data": {
        "header_label": "Portfolio",
        "display_value": "$24,800",
        "display_subtitle": "5 positions",
        "stats": [{ "label": "P&L", "value": "+$1,200", "trend": "up" }]
      }
    }
  }'
Components

21 Component Types

Each widget declares up to 3 component types. Choose from Basic, Data, and Interactive types depending on what best represents your platform's data.

Basic
12

Stats & Content

Numbers, lists, text blocks, tags, avatars. The everyday workhorses.

stat_value stat_row stat_grid progress_bar progress_ring list_items tag_cloud text_block avatar_stack icon_grid hero_card split_card
Data
6

Visualisations

Charts, timelines, images, ranked lists. For platforms with rich structured data.

bar_chart sparkline radar_chart comparison_bar ranked_list timeline
Interactive
3

Tappable Actions

Buttons and links that open URLs in the browser. Drive traffic and deep links.

cta_banner action_row image_row

See full schemas and example payloads in the Component Reference →

Ready to build?

Register your widget, verify your domain, and push your first data in minutes.

Create account →