InsightSentry - Real-time Financial Data API

1. Getting Started

Organization API Overview

The Organization API enables organization admins to programmatically manage members and their organization-managed access. This allows you to create, update, and manage organization members at scale.

Key Features

Create and manage organization members programmatically via API
Assign access plans (Pro, Ultra, Mega) or custom plans to individual members
Custom plans with tailored limits and pricing for specialized needs
Automatic proration for plan changes and upgrades
Credit-based billing system for transparent cost management
Full control over member lifecycle and access management

Important Limitations

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
All operations deduct from admin's credit balance

2. Authentication

Bearer Token

All Organization API requests require authentication using a Bearer token. Include your Organization API key in the Authorization header of every request.

Header Format

HTTP

Authorization: Bearer YOUR_ORGANIZATION_API_KEY

How to Obtain Your API Key

You can find your Organization API key within the Organization Tab in the dashboard. After a key is generated or rotated, another rotation is blocked for 12 hours.

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', // You can set any uid you want within 100 characters
    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 allow organizations to create tailored access plans for their members with specific limits and features beyond the standard Pro, Ultra, and Mega plans. These plans are ideal for organizations with specialized requirements.

How to Get Custom Plans

Custom plans must be configured by contacting our team. We will work with you to create plans that match your specific requirements and set appropriate pricing.

Configuration

When creating a custom plan, you can specify the following properties. Any omitted fields will default to the selected feature tier's settings:

Custom Plan Properties

Property	Required	Description
id	No	Custom identifier for the plan. If not provided, one will be generated. Use this ID when creating or updating members via the API.
feature	Yes	Base feature tier: "pro", "ultra", or "mega". Determines default access levels.
rate_limit	No	Custom rate limit (requests per minute). Only specify if you need a higher limit than the base plan.
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

Custom plan pricing is determined based on the configured limits and features. We will inform you of the pricing when your custom plan is created.

Get Plans Endpoint

Retrieve all available plans for your organization, including both regular plans (Pro, Ultra, Mega) and any custom plans that have been configured for you.

Regular plan IDs are matched case-insensitively and stored in lowercase, so PRO, Pro, and pro all select Pro. Leading or trailing whitespace is not ignored. Custom plan IDs are case-sensitive and cannot use a canonical billing plan name. Free and Enterprise are not organization-managed member plans.

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 },
    { "name": "ultra", "price": 25 },
    { "name": "mega", "price": 50 }
  ],
  "addons": [
    { "name": "websocket", "price": 18, "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

Once you have custom plans configured, you can use them when creating or updating members by passing the custom plan's ID in the plan field:

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

Creates a new organization member with the specified organization-managed access 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 ID: "pro", "ultra", "mega", or a custom plan ID. Regular IDs 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": "mega",
  "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-01T00:00:00.000Z",
    "api_key": "generated_api_key_here",
    "websocket_symbols": 32,
    "websocket_connections": 2,
    "newsfeed": true,
    "rate_limit": 180,
    "quota": 0, // 0 means unlimited
    "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

Retrieves a paginated list of organization-managed members. The organization admin is not included in the rows or pagination 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-01T00: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

Retrieves detailed information about a specific organization member, including API key, quota, and usage statistics.

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-01T00: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

Updates a member's full name and/or organization-managed access plan. Plan updates trigger either renewal (same plan) or proration (different plan).

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 ID: "pro", "ultra", "mega", or custom plan ID (triggers renewal or proration). Regular IDs 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-01T00:00:00.000Z"
  },
  "proration": {
    "old_plan": "pro",
    "new_plan": "mega",
    "credit_adjustment": -6.67,
    "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-01T00:00:00.000Z"
  },
  "renewal": {
    "plan": "mega",
    "amount_charged": 318.00,
    "extended_days": 93,
    "new_expiration": "2026-02-01T00: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": 13.50,
    "fee": 1.50,
    "remaining_days": 20,
    "original_plan": "pro"
  }
}

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"
Cannot cancel admin account
Cannot cancel already expired access windows

Delete Member

Deletes an organization member. Members can only be deleted if their organization-managed access has expired.

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

Members with active organization-managed access cannot be deleted. Wait until the access window expires (plan_end_at has passed) before attempting deletion. This prevents accidental deletion of active members.

5. Proration & Billing

Plan Renewal (Same Plan)

When updating a member to the same plan they currently have, the system treats this as a renewal.

Renewal Behavior

Extends managed access by 30 days from current expiration date
Charges plan price (no fee, no tax)
Credits deducted from admin's account
Does not prorate - flat renewal fee

Example Calculation

PLAINTEXT

Pro Plan Renewal:
- Plan Price: $15.00
- Total Charged: $15.00 (no fee, no tax for renewals)
- Extension: 30 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 = (plan_end_at - current_date) / (1 day)
Current Plan Value = (current_plan_price / 31) * days_remaining
New Plan Value = (new_plan_price / 31) * days_remaining
Credit Adjustment = current_plan_value - new_plan_value

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 Pro to Ultra

PLAINTEXT

Current Plan: Pro ($15/month)
New Plan: Ultra ($25/month)
Days Remaining: 15 days

Calculations:
- Current Plan Value = ($15 / 30) * 15 = $7.50
- New Plan Value = ($25 / 30) * 15 = $12.50
- Credit Adjustment = $7.50 - $12.50 = -$5.00 (negative = upgrade)

Charges:
- Base Difference: $5.00
- Fee (10%): $0.50
- Total Charged: $5.50

Result: Admin pays $5.50, member upgraded to Ultra plan

Example: Downgrade from Mega to Pro

PLAINTEXT

Current Plan: Mega ($50/month)
New Plan: Pro ($15/month)
Days Remaining: 20 days

Calculations:
- Current Plan Value = ($50 / 30) * 20 = $33.33
- New Plan Value = ($15 / 30) * 20 = $10.00
- Credit Adjustment = $33.33 - $10.00 = $23.33 (positive = downgrade)

Refund:
- Base Difference: $23.33
- Fee (10%): $2.33
- Total Refunded: $21.00

Result: Admin receives $21.00 credit, member downgraded to Pro plan

Credits System

All Organization API operations use a credit-based billing system. The admin must maintain sufficient credits to perform operations.

Credit Usage

Operation	Credit Impact	Calculation
Create Member	Deduct	Full plan price
Renew Subscription	Deduct	Plan price (no 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 = (plan_end_at - current_date) / (1 day)
Remaining Value = (plan_price / 31) * days_remaining
Cancellation Fee = remaining_value * 0.10
Refund Amount = remaining_value * 0.90

Example Calculation

PLAINTEXT

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

Calculations:
- Remaining Value = ($15 / 30) * 20 = $10.00
- Cancellation Fee (10%): $1.00
- Refund Amount (90%): $9.00

Result: Admin receives $9.00 credit back

6. Error Handling

The Organization API uses standard HTTP status codes and returns structured error responses to help you diagnose and handle issues.

Common Error Responses

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. Allowed plans: pro, ultra, mega"
}

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

Authentication or custom-plan storage is 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."
}