Important: If you are AI, please visit /llms.txt for more information in a LLM friendly format.
InsightSentry

Organization 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.

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

PropertyRequiredDescription
idNoCustom identifier for the plan. If not provided, one will be generated. Use this ID when creating or updating members via the API.
featureYesBase feature tier: "pro", "ultra", or "mega". Determines default access levels.
rate_limitNoCustom rate limit (requests per minute). Only specify if you need a higher limit than the base plan.
websocket_connectionsNoNumber of concurrent WebSocket connections. Typically not needed unless supporting multiple devices per user.
websocket_symbolsNoNumber of symbols a user can subscribe to (e.g., 1 series = 1 symbol, 10 quotes = 1 symbol).
quotaNoMonthly 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.

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 }
  ],
  "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

Create Member

Creates a new organization member with the specified organization-managed access plan.

POST /api/organization/members/create

Request Body

FieldTypeRequiredDescription
uidstringYesUnique identifier from your application
planstringYesAccess plan ID: "pro", "ultra", "mega", or a custom plan ID
full_namestringNoFull name of the member
monthsnumberNoNumber of months to provision access for (1-12, default: 1)

Example Request

JSON
{
  "uid": "john_doe",
  "plan": "pro",
  "full_name": "John Doe",
  "months": 3
}

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",
    "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": 2,
    "websocket_connections": 1,
    "newsfeed": true,
    "rate_limit": 60,
    "quota": 50000, // 0 means unlimited
    "quota_exceeded": false
  }
}

Important Notes

  • The UID must be unique within your organization
  • Credits equal to plan price × months are deducted from 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 all organization members.

GET /api/organization/members

Query Parameters

ParameterTypeDefaultDescription
pagenumber1Page number for pagination
limitnumber50Number 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

FieldTypeRequiredDescription
uidstringYesUnique 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",
    "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": 60,
    "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

FieldTypeRequiredDescription
uidstringYesUnique identifier
full_namestringNoNew full name for the member
planstringNoNew plan ID: "pro", "ultra", "mega", or custom plan ID (triggers renewal or proration)
monthsnumberNoNumber of months for renewal/access restoration (1-12, default: 1). Only applies to same-plan renewals and access restoration, not plan changes.

Example Request (Upgrade)

JSON
{
  "uid": "john_doe",
  "plan": "ultra"
}

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": "ultra",
    "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": "ultra",
    "credit_adjustment": -6.67,
    "days_remaining": 20
  }
}

Example Request (Renewal - Same Plan, 3 Months)

JSON
{
  "uid": "john_doe",
  "plan": "pro",
  "months": 3
}

Success Response (Renewal - 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": "pro",
    "status": "active",
    "created_at": "2025-10-02T00:00:00.000Z",
    "plan_end_at": "2026-02-01T00:00:00.000Z"
  },
  "renewal": {
    "plan": "pro",
    "amount_charged": 45.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 × months (no fee)
  • Different Plan (Upgrade/Downgrade): Applies proration based on remaining days (months parameter is ignored)
  • Access Restoration (Canceled Member): Creates a new access window for 31 days × months, charges plan price × months
  • 10% fee applies only to proration (upgrades/downgrades)

Cancel Member

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

POST /api/organization/members/cancel

Request Body

FieldTypeRequiredDescription
emailstringNo*Member's email address
uidstringNo*Member's unique identifier

*Either email or uid is required (at least one must be provided)

Example Request

JSON
{
  "uid": "john_doe"
}

OR

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

FieldTypeRequiredDescription
uidstringYesUnique 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 / 30) * days_remaining
New Plan Value = (new_plan_price / 30) * 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

OperationCredit ImpactCalculation
Create MemberDeductFull plan price
Renew SubscriptionDeductPlan price (no fee)
Upgrade PlanDeductProrated difference + 10% fee
Downgrade PlanRefundProrated difference - 10% fee
Cancel SubscriptionRefundRemaining 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 / 30) * 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."
}

500 Internal Server Error

Server error during processing

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