InsightSentry - Real-time Financial Data API

1. Getting Started

Create, update, and manage organization members.

Organization OpenAPI Specification

Import this specification into your API tools or generate a client SDK for the Organization API.

View specification Download JSON

Member access

Users created via API cannot log in to the dashboard
Members are only manageable by the admin via API or dashboard
Members' organization-managed access windows do not auto-renew - admin must manually renew via API

2. Authentication

Send your Organization API key as a Bearer token on every request:

HTTP

Authorization: Bearer YOUR_ORGANIZATION_API_KEY

How to Obtain Your API Key

Find your key in the dashboard's Organization tab. Key rotations must be at least 12 hours apart.

Example Request

TYPESCRIPT

const apiKey = 'your_organization_api_key';

const response = await fetch('https://insightsentry.com/api/organization/members/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uid: 'john_doe',
    plan: 'pro',
    full_name: 'John Doe'
  })
});

const data = await response.json();
console.log(data);

Security Best Practices

Store API keys in environment variables, never in code
Rotate API keys periodically for enhanced security
Monitor API usage for unusual patterns

3. Custom Plans

Overview

Custom plans define member access settings.

How to Get Custom Plans

Contact support to configure a custom plan.

Configuration

Omitted fields use the selected feature tier's defaults.

Custom Plan Properties

Property	Required	Description
name	Yes	Custom plan identifier returned by the plans endpoint. Pass this value in `plan` when creating or updating a member.
feature	Yes	Base feature tier: "pro", "ultra", or "mega". Determines default access levels.
rate_limit	No	Requests per minute. Omit to use the selected feature tier's default.
websocket_connections	No	Number of concurrent WebSocket connections. Typically not needed unless supporting multiple devices per user.
websocket_symbols	No	Number of symbols a user can subscribe to (e.g., 1 series = 1 symbol, 10 quotes = 1 symbol).
quota	No	Monthly REST API request limit. Can be set to 0 for unlimited requests.

Pricing

Pricing is confirmed when the custom plan is created.

Get Plans Endpoint

List standard and custom plans for your organization.

Create and update requests accept Starter (pro or starter), Growth (ultra or growth), and Scale (mega or scale). These names are case-insensitive; leading or trailing whitespace is not ignored. Responses keep the canonical IDs pro, ultra, and mega. Use display_name for labels and aliases for accepted alternative inputs. Custom plan IDs are case-sensitive. New custom plans cannot use a regular ID or alias. Free and Enterprise are not organization-managed member plans.

If an alias conflicts with an existing custom plan, the request returns 409 without applying changes. Use the canonical ID to choose the regular plan. Existing custom plans retain their names; omit plan when updating only member details.

GET /api/organization/plans

Example Request

BASH

curl -X GET "https://insightsentry.com/api/organization/plans" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

JSON

{
  "success": true,
  "regular_plans": [
    { "name": "pro", "price": 15, "display_name": "Starter", "aliases": ["starter"] },
    { "name": "ultra", "price": 25, "display_name": "Growth", "aliases": ["growth"] },
    { "name": "mega", "price": 50, "display_name": "Scale", "aliases": ["scale"] }
  ],
  "addons": [
    { "name": "websocket", "price": 12, "step": 10, "unit": "subscriptions", "max_quantity": 10, "eligible_plans": ["mega"] },
    { "name": "rate_limit", "price": 20, "step": 100, "unit": "req/min", "max_quantity": 20, "eligible_plans": ["mega"] }
  ],
  "custom_plans": [
    {
      "name": "ultra_plus",
      "price": 40,
      "feature": "ultra",
      "rate_limit": 80,
      "websocket_connections": 1,
      "websocket_symbols": 5,
      "quota": 0
    }
  ]
}

Using Custom Plans

Pass the plan name in plan when creating or updating a member:

JSON

{
  "uid": "john_doe",
  "plan": "ultra_plus"
}

4. API Endpoints

Member lookup, update, cancel, and delete requests accept exactly one selector: either email or uid, but not both. UIDs are 1-100 characters and may contain letters, numbers, and _!/.=- only.

Create Member

Create a member with the specified plan.

POST /api/organization/members/create

Request Body

Field	Type	Required	Description
uid	string	Yes	Unique identifier from your application (1-100 characters; letters, numbers, and `_!/.=-` only)
plan	string	Yes	Access plan: "pro"/"starter", "ultra"/"growth", "mega"/"scale", or a custom plan ID. Regular IDs and aliases are case-insensitive; custom IDs are case-sensitive.
full_name	string	No	Full name of the member
months	number	No	Number of months to provision access for (1-12, default: 1)
addons	object	No	Addon quantities: `websocket` and `rate_limit`. Regular addon eligibility and maximum quantities apply.

Example Request

JSON

{
  "uid": "john_doe",
  "plan": "scale",
  "full_name": "John Doe",
  "months": 3,
  "addons": { "websocket": 2, "rate_limit": 1 }
}

Success Response

JSON

{
  "success": true,
  "member": {
    "uid": "john_doe",
    "email": "org_john_doe@company.com",
    "full_name": "John Doe",
    "role": "member",
    "access_model": "organization_managed",
    "plan": "mega",
    "addons": { "websocket": 2, "rate_limit": 1 },
    "status": "active",
    "created_at": "2025-10-02T00:00:00.000Z",
    "plan_end_at": "2026-01-03T00:00:00.000Z",
    "api_key": "generated_api_key_here",
    "websocket_symbols": 32,
    "websocket_connections": 2,
    "newsfeed": true,
    "rate_limit": 180,
    "quota": 0,
    "quota_exceeded": false
  }
}

Important Notes

The UID must be unique within your organization
Credits equal to (plan price + addon prices) × months are deducted from the admin's account
The access window is active for 31 days × months from creation (e.g., 3 months = 93 days)

List Members

List members with pagination. The administrator is excluded from results and totals.

GET /api/organization/members

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Positive integer page number
limit	integer	50	Positive integer number of members per page (max: 50)

Example Request

BASH

curl -X GET "https://insightsentry.com/api/organization/members?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

JSON

{
  "success": true,
  "members": [
    {
      "uid": "john_doe",
      "email": "org_john_doe@company.com",
      "full_name": "John Doe",
      "role": "member",
      "plan": "pro",
      "status": "active",
      "created_at": "2025-10-02T00:00:00.000Z",
      "plan_end_at": "2025-11-02T00:00:00.000Z"
    },
    {
      "uid": "jane_smith",
      "email": "org_jane_smith@company.com",
      "full_name": "Jane Smith",
      "role": "member",
      "plan": "ultra",
      "status": "active",
      "created_at": "2025-10-01T00:00:00.000Z",
      "plan_end_at": "2025-11-05T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "total_pages": 3
  }
}

Get Member

Get a member's API key, quota, and usage.

POST /api/organization/members/get

Request Body

Field	Type	Required	Description
email	string	No*	Member's email address
uid	string	No*	Unique identifier

Example Request

JSON

{
  "uid": "john_doe"
}

Success Response

JSON

{
  "success": true,
  "member": {
    "uid": "john_doe",
    "email": "org_john_doe@company.com",
    "full_name": "John Doe",
    "role": "member",
    "access_model": "organization_managed",
    "plan": "pro",
    "addons": { "websocket": 0, "rate_limit": 0 },
    "status": "active",
    "created_at": "2025-10-02T00:00:00.000Z",
    "plan_end_at": "2025-11-02T00:00:00.000Z",
    "api_key": "member_api_key_here",
    "websocket_symbols": 2,
    "websocket_connections": 1,
    "newsfeed": true,
    "rate_limit": 25,
    "quota": 50000,
    "quota_exceeded": false,
    "quota_reset_time": "2025-10-03T00:00:00.000Z"
  }
}

Update Member

Update a member's name or plan. Keeping the same plan renews access; changing plans applies proration.

POST /api/organization/members/update

Request Body

Field	Type	Required	Description
email	string	No*	Member's email address
uid	string	No*	Unique identifier
full_name	string	No	New full name for the member
plan	string	No	New plan: "pro"/"starter", "ultra"/"growth", "mega"/"scale", or a custom plan ID (triggers renewal or proration). Regular IDs and aliases are case-insensitive; custom IDs are case-sensitive.
months	number	No	Number of months for renewal/access restoration (1-12, default: 1). Only applies to same-plan renewals and access restoration, not plan changes.
addons	object	No	Desired addon quantities. Omitted addon keys keep their current quantities; setting a quantity to 0 removes that addon with proration.

Example Request (Plan and Addon Update)

JSON

{
  "uid": "john_doe",
  "plan": "mega",
  "addons": {
    "websocket": 2,
    "rate_limit": 1
  }
}

Success Response (Upgrade with Proration)

JSON

{
  "success": true,
  "member": {
    "uid": "john_doe",
    "email": "org_john_doe@company.com",
    "full_name": "John Doe",
    "role": "member",
    "access_model": "organization_managed",
    "plan": "mega",
    "addons": { "websocket": 2, "rate_limit": 1 },
    "status": "active",
    "created_at": "2025-10-02T00:00:00.000Z",
    "plan_end_at": "2025-11-02T00:00:00.000Z"
  },
  "proration": {
    "old_plan": "pro",
    "new_plan": "mega",
    "credit_adjustment": -58.71,
    "days_remaining": 20
  }
}

Example Request (Renewal with Addons - Same Plan, 3 Months)

JSON

{
  "uid": "john_doe",
  "plan": "mega",
  "months": 3
}

Success Response (Renewal with Addons - Same Plan, 3 Months)

JSON

{
  "success": true,
  "member": {
    "uid": "john_doe",
    "email": "org_john_doe@company.com",
    "full_name": "John Doe",
    "role": "member",
    "access_model": "organization_managed",
    "plan": "mega",
    "addons": { "websocket": 2, "rate_limit": 1 },
    "status": "active",
    "created_at": "2025-10-02T00:00:00.000Z",
    "plan_end_at": "2026-02-03T00:00:00.000Z"
  },
  "renewal": {
    "plan": "mega",
    "amount_charged": 318.00,
    "extended_days": 93,
    "new_expiration": "2026-02-03T00:00:00.000Z"
  }
}

Plan Update Behavior

Same Plan (Renewal): Extends managed access by 31 days × months, charges (plan price + active addon prices) × months (no fee)
Different Plan (Upgrade/Downgrade): Applies proration based on remaining days; addon quantity changes use the same proration calculation
Access Restoration (Canceled Member): Creates a new access window for 31 days × months, charges (plan price + addon prices) × months
10% fee applies only to proration (upgrades/downgrades)

Cancel Member

Cancels a member's organization-managed access with 90% refund of remaining value including active addon value (10% cancellation fee applies).

POST /api/organization/members/cancel

Request Body

Field	Type	Required	Description
email	string	No*	Member's email address
uid	string	No*	Member's unique identifier

*Provide exactly one of email or uid

Example Request

JSON

{
  "uid": "john_doe"
}

JSON

{
  "email": "org_john_doe@company.com"
}

Success Response (200)

JSON

{
  "success": true,
  "message": "Member access canceled successfully",
  "refund": {
    "amount": 8.71,
    "fee": 0.97,
    "original_remaining_value": 9.68,
    "days_refunded": 20
  }
}

Error Responses

400 Bad Request

Invalid request or already canceled

JSON

{
  "success": false,
  "error": "Member access is already inactive"
}

404 Not Found

Member not found

JSON

{
  "success": false,
  "error": "Member not found"
}

409 Conflict

Direct PayPal subscriber

JSON

{
  "success": false,
  "error": "Cannot cancel member with direct subscription. Only organization-managed members can be canceled."
}

429 Too Many Requests

Rate limit exceeded

JSON

{
  "success": false,
  "error": "Too many requests. Please try again later."
}

Important Notes

Only organization-managed members can be canceled via API
Direct PayPal subscribers must cancel through PayPal
Cancellation includes 10% fee, 90% refund of remaining value
Admin's credit balance is increased by the refund amount
Canceled members will have status "canceled"
API access continues for one day after cancellation
Cannot cancel admin account
Cannot cancel already expired access windows

Delete Member

Deletes an organization member. Cancel active organization-managed access or wait for it to expire before deleting the member. Deleted UIDs remain reserved.

POST /api/organization/members/delete

Request Body

Field	Type	Required	Description
email	string	No*	Member's email address
uid	string	No*	Unique identifier

Example Request

JSON

{
  "uid": "john_doe"
}

Success Response

JSON

{
  "success": true,
  "message": "Member deleted successfully"
}

Deletion Restrictions

Cancel active access first, or wait until plan_end_at has passed.

5. Proration & Billing

Plan Renewal (Same Plan)

Sending the same plan with unchanged addon quantities renews active access. Addon quantity changes use proration; canceled or expired access starts a new access window.

Renewal Behavior

Extends managed access by 31 days × months from the current expiration date
Charges (plan price + addon prices) × months, with no renewal fee
Credits deducted from admin's account
Charges full months without proration

Example Calculation

PLAINTEXT

Starter Plan Renewal:
- Plan Price: $15.00
- Total Charged: $15.00 (no fee, no tax for renewals)
- Extension: 31 days from current plan_end_at

Plan Change (Upgrade/Downgrade)

When changing to a different plan, the system applies proration based on the remaining days in the current access window.

Proration Formula

PLAINTEXT

Days Remaining = ceil((plan_end_at - current_date) / (1 day))
Current Plan Value = ((current_plan_price + current_addon_prices) / 31) * days_remaining
New Plan Value = ((new_plan_price + new_addon_prices) / 31) * days_remaining
Credit Adjustment = current_plan_value - new_plan_value
Round each remaining value, the adjustment, and the fee to two decimal places.

If Credit Adjustment < 0 (Upgrade):
  Amount Charged = |credit_adjustment| + (|credit_adjustment| * 0.10)

If Credit Adjustment > 0 (Downgrade):
  Amount Refunded = credit_adjustment - (credit_adjustment * 0.10)

Example: Upgrade from Starter to Growth

PLAINTEXT

Current Plan: Starter ($15/month)
New Plan: Growth ($25/month)
Days Remaining: 15 days

Calculations:
- Current Plan Value = ($15 / 31) * 15 = $7.26
- New Plan Value = ($25 / 31) * 15 = $12.10
- Credit Adjustment = $7.26 - $12.10 = -$4.84 (negative = upgrade)

Charges:
- Base Difference: $4.84
- Fee (10%): $0.48
- Total Charged: $5.32

Result: Admin pays $5.32, member upgraded to Growth plan

Example: Downgrade from Scale to Starter

PLAINTEXT

Current Plan: Scale ($50/month)
New Plan: Starter ($15/month)
Days Remaining: 20 days

Calculations:
- Current Plan Value = ($50 / 31) * 20 = $32.26
- New Plan Value = ($15 / 31) * 20 = $9.68
- Credit Adjustment = $32.26 - $9.68 = $22.58 (positive = downgrade)

Refund:
- Base Difference: $22.58
- Fee (10%): $2.26
- Total Refunded: $20.32

Result: Admin receives $20.32 credit, member downgraded to Starter plan

Credits System

Member purchases use the admin's credit balance. Reads, name-only updates, and deletion do not deduct credits.

Credit Usage

Operation	Credit Impact	Calculation
Create Member	Deduct	(Plan price + addon prices) × months
Renew Subscription	Deduct	(Plan price + addon prices) × months, no renewal fee
Upgrade Plan	Deduct	Prorated difference + 10% fee
Downgrade Plan	Refund	Prorated difference - 10% fee
Cancel Subscription	Refund	Remaining value - 10% fee

Transaction Logging

All credit transactions are logged in the Credit Usage Section in the dashboard.

Cancellation & Refunds

When canceling a member's managed access, a 10% cancellation fee is applied, and 90% of the remaining access value is refunded to the admin's credit balance.

Cancellation Formula

PLAINTEXT

Days Remaining = ceil((plan_end_at - current_date) / (1 day))
Remaining Value = ((plan_price + addon_prices) / 31) * days_remaining
Cancellation Fee = remaining_value * 0.10
Refund Amount = remaining_value - cancellation_fee
Round remaining value, the fee, and the refund to two decimal places.

Example Calculation

PLAINTEXT

Plan: Starter ($15/month)
Days Remaining: 20 days

Calculations:
- Remaining Value = ($15 / 31) * 20 = $9.68
- Cancellation Fee (10%): $0.97
- Refund Amount (90%): $8.71

Result: Admin receives $8.71 credit back

6. Error Handling

Errors include an HTTP status and a JSON response.

401 Unauthorized

Invalid or missing API key in Authorization header

JSON

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

400 Bad Request

Invalid request body or parameters

JSON

{
  "success": false,
  "error": "Invalid plan: 'gold'. Must be a regular plan (pro/starter, ultra/growth, mega/scale) or a valid custom plan name."
}

404 Not Found

Member not found

JSON

{
  "success": false,
  "error": "Member not found"
}

409 Conflict

Resource conflict (e.g., member already exists or has active managed access)

JSON

{
  "success": false,
  "error": "Cannot delete member with active organization-managed access. Expires: 2025-11-01"
}

402 Payment Required

Insufficient credits for operation

JSON

{
  "success": false,
  "error": "Insufficient credits. Required: 25.00, Available: 10.00"
}

429 Too Many Requests

Rate limit exceeded

JSON

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later."
}

503 Service Unavailable

Service temporarily unavailable. Retry with backoff.

JSON

{
  "success": false,
  "error": "Service temporarily unavailable"
}

500 Internal Server Error

Server error during processing

JSON

{
  "success": false,
  "error": "An internal error occurred. Please try again or contact support."
}