Push Notification
Email Alert
> We recommend rendering the iframe on a dedicated page (e.g., “Manage Subscriptions”) to give users full access to ScribeUp’s features.
- name: widget
x-displayName: "Preview Widget Integration"
description: |-
You can embed ScribeUp's pre-built preview widget modules directly into your homepage or other surfaces of your app to drive engagement and visibility. If you'd prefer to use your own design, you can connect to ScribeUp's Reporting API to power your own preview widget.
### Pre-Built Preivew Widget
**ScribeUp's Pre-Built Modules** (via SDK or iframe):
- **Calendar View** (`/calendar-preview`): Show recent and upcoming subscriptions and bills in a calendar layout.
- **List View** (`/list-preview`): Display a scrollable list of upcoming charges.
These modules can be delivered via iframe or SDK depending on your platform.
**Preview Widget UI States**: The embedded experience includes built-in states:
- Onboarding (first-time setup)
- No upcoming charges
- Active subscriptions and bills
- Calendar display
### Native Widget (Custom UI using APIs)
If you prefer to build a native UI, you can use ScribeUp's [Reporting API](#tag/Reporting) to retrieve the same bill, renewal, and account insights and render them in your own components.
- name: Transactions Integration
x-displayName: Transactions Integration
description: |-
ScribeUp uses your internal transactions data to identify recurring subscriptions and bills. You can either connect your Transactions API, use batch file delivery (e.g., SFTP or reverse ETL), or use webhooks.
#### Integration Options:
- **API Connection** (recommended): Connect your existing Transactions API to ScribeUp
- **Batch Sync**: Use daily/weekly reverse ETL pipelines or share files via SFTP
- **Webhooks**: Push real-time or batched transaction events directly to ScribeUp
It's recommended that you provide at least **24 months** of transaction history per user for best detection accuracy.
Each transaction should include the following fields:
- **Required:**
- `id`: Unique identifier for the transaction
- `user_id`: Client's unique identifier for user
- `authorized_datetime`: Timestamp of authorization
- `datetime`: Timestamp when the transaction posted/settled
- `status`: Transaction status (e.g., `pending`, `closed`, `reversed`)
- `amount`: Decimal amount
- `currency`: ISO currency code
- `description`: Raw transaction description string
- `country`: ISO alpha-2 country code (e.g., `US`)
- `account_id`: ID of the related account
- `account_metadata`: Optional if not provided via separate API
- `account_name`
- `account_mask`
- `account_type` (e.g., `depository`)
- `account_subtype` (e.g., `checking`)
**Optional:**
- `type`: Transaction type (e.g., `online`, `pos`)
- `mcc`: Merchant Category Code
#### Example Transaction Payload:
```json
{
"id": "5cafaab8-535a-44ee-9bb3-03be4326fc39",
"user_id": "user123",
"authorized_datetime": "2024-07-24T19:13:02",
"datetime": "2024-07-24T19:13:02",
"status": "closed",
"amount": 9.97,
"currency": "USD",
"description": "APPLE.COM/BILL",
"country": "US",
"account_id": "2b8abcb5-3ce6-4882-b093-ce737b0dd3d9",
"account_metadata": {
"account_name": "Personal Checking",
"account_mask": "4567",
"account_type": "depository",
"account_subtype": "checking",
}
"mcc": 1234,
"type": "online"
}
```
- name: Plaid Integration
x-displayName: Plaid Integration
description: |-
ScribeUp integrates with your existing **Plaid** instance using **processor tokens**, allowing users to connect external accounts and enabling ScribeUp to scan those accounts for recurring subscriptions and bills.
#### Why use your Plaid instance?
Using your existing Plaid connection offers several advantages:
- **No duplicate account linking**: Reuse accounts already linked in your app.
- **Control the data**: You own and manage all external account and transaction data.
- **System-wide benefits**: Linked accounts can also power funding sources, fraud checks, and other internal tools.
If you'd prefer not to integrate with your own Plaid keys, **ScribeUp can provide Plaid access on your behalf** — no extra engineering required. We'll handle the entire Plaid flow and transaction ingestion.
### Integration Overview
**Step 1: Client Hosts the Plaid Link Flow**
- Embed and manage your own Plaid Link UX (either in-app or via deep link).
- Generate processor tokens (`p-tokens`) using the Plaid processor ID `scribeup`.
- See [Plaid's documentation](https://plaid.com/docs/api/processors/#processortokencreate) for guidance on processor token creation.
**Step 2: Notify ScribeUp via Webhook**
- After generating processor tokens, notify ScribeUp using this endpoint:
```
POST /api/v1/webhook/external-accounts
```
**Step 3: Expose API for ScribeUp to Fetch Tokens**
- Create a secure endpoint ScribeUp can call to retrieve all processor tokens for a given user.
**Sample Contract**
```
GET /v1/users/{user_id}/processor_tokens
```
**Example Code (python)**
```python
# Exchange the public token from Plaid Link for an access token.
exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token)
exchange_token_response = client.item_public_token_exchange(exchange_request)
access_token = exchange_token_response['access_token']
# Fetch all accounts for this access token
accounts_request = AccountsGetRequest(access_token=access_token)
accounts_response = client.accounts_get(accounts_request)
accounts = accounts_response['accounts']
# Create processor tokens for all accounts
ptokens = []
for account in accounts:
create_request = ProcessorTokenCreateRequest(
access_token=access_token,
account_id=account['account_id'],
processor='scribeup'
)
create_response = client.processor_token_create(create_request)
ptokens.append(create_response['processor_token'])
return Response({"data": {"plaid_processor_tokens": ptokens}}, status.HTTP_200_OK)
```
**Expected Response**
```json
{
"data": {
"plaid_processor_tokens": [
"processor-sandbox-123abc",
"processor-sandbox-456def"
]
}
}
```
- Input: `user_id` (your internal identifier, also passed to ScribeUp during auth)
- Output: All processor tokens for linked accounts
- Store generated tokens or use saved access tokens to regenerate them on demand
- ScribeUp will authenticate using pre-shared API keys or credentials
**Redirect after Plaid Flow**
- Once the user finishes Plaid linking, redirect them back to ScribeUp to continue onboarding.
### Optional: Notify on Account Updates
If a user adds or removes accounts in your experience, you can trigger a refresh by notifying ScribeUp using the webhook above. **This process is detailed below.**
### Don’t have a Plaid integration?
ScribeUp can provide and manage the full Plaid linking experience on your behalf. Users can securely link accounts directly inside the Subscription Manager flow with no client-side implementation required.
- name: Reporting
x-displayName: Reporting API
description: |-
The Reporting API allows you to retrieve real-time user-level data from Subscription Manager, including active subscriptions, bills, linked accounts, and recurrence insights.
This is ideal if:
- You want to build a **custom, native UI** instead of using ScribeUp’s SDK or iframe
- You need to surface **subscription intelligence** elsewhere in your app
- You want to integrate user-level data into **internal dashboards or analytics tools**
### Common Use Cases
- Power a **native widget** with real-time upcoming charges
- Show personalized savings insights or alerts in your feed
- Visualize linked accounts and track bill payment history
- Use recurrence data to inform internal credit risk or churn models
- name: Notification Webhook
x-displayName: Notification Webhook
description: |-
This section explains how to receive real-time notifications from ScribeUp via webhook.
You can use this to power both:
- **Activation alerts**: For users who have activated Subscription Manager
- **Pre-activation alerts**: For users who haven't yet activated Subscription Manager but should still receive nudges
The webhook is designed to be used with your **CRM**, **marketing automation platform**, or **notifications infrastructure** to deliver push, email, or SMS messages.
### 1. Webhook Setup
ScribeUp sends a `POST` request to your configured webhook endpoint whenever a notification should be delivered to a user.
- **Method**: `POST`
- **Content-Type**: `application/json`
- **Sample Payload**:
```json
{
"id": "19cde91e-86d8-465a-80e5-fca40fb6e9dc",
"user_id": "123456",
"email": "user@example.com",
"user_status": "active",
"type": "bill_reminder",
"merchant_names": ["Netflix", "Hulu"],
"merchant_ids": ["netflix_001", "hulu_002"],
"channels": ["email", "push"],
"email_subject": "Your subscriptions are renewing soon",
"email_content": "Netflix, Hulu, and 2 other services are renewing this week.",
"push_title": "2 renewals this week",
"push_body": "Netflix and Hulu are renewing soon",
"recurrences": [
{
"id": "ff04d458-c376-42d4-8cae-6ae5ccbf5dce",
"type": "subscription",
"status": "active",
"merchant": {
"id": "netflix_001",
"url": "netflix.com",
"name": "Netflix",
"logo_url": "https://example.com/logos/netflix.png"
},
"frequency": "monthly",
"loan_type": null,
"account_id": "65e3ab74-4cc0-4240-babf-a6956d7d780c",
"amount_cents": 1599,
"last_payment_date": "2025-04-18T06:57:08Z",
"next_payment_date": "2025-05-18T06:57:08Z",
"total_amount_cents": 4797,
"monthly_amount_cents": 1599
},
{
"id": "a8006635-f5ce-4863-819b-fa787eaa6746",
"type": "subscription",
"status": "active",
"merchant": {
"id": "hulu_002",
"url": "hulu.com",
"name": "Hulu",
"logo_url": "https://example.com/logos/hulu.png"
},
"frequency": "monthly",
"loan_type": null,
"account_id": "65e3ab74-4cc0-4240-babf-a6956d7d780c",
"amount_cents": 799,
"last_payment_date": "2025-04-20T06:57:08Z",
"next_payment_date": "2025-05-20T06:57:08Z",
"total_amount_cents": 2397,
"monthly_amount_cents": 799
}
]
}
```
card_id, user_id, and a Base-64 PEM public_key.