integrations

Start a recurring add-on (internal)

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}
Close
POST /admin/orgs/{orgId}/recurring-addons
Access token

Starts a recurring add-on for the organization (kit or laptop rental billed monthly, live bank every six months), optionally tied to case, with periods anchored on the day of startedAt (now by default). Repeating the same organization, SKU and externalRef returns the existing record instead of starting a second one; returns 400 for a SKU that is not a recurring add-on or an organization without a case-billing profile. Super admin only.

Path parameters

  • orgId string Required

    Id of the organization

application/json

Body Required

  • skuKey string Required

    Must be a recurring add-on (kit rental, laptop rental, live bank). One-time charges go through the billing-item endpoint.

    Values are collection.phone, collection.social, collection.email, collection.ai-chat, collection.financial, collection.discord, collection.reddit, collection.linkedin, collection.legal, collection.file, collection.other, case.flat, case.pro-upgrade, addon.kit-rental, addon.laptop-rental, addon.laptop-rental-setup, addon.managed-service, addon.shipping, addon.live-bank, plan.base, source.per, ai.tokens-overage, adjustment.manual, or adjustment.discount.

  • externalRef string Required

    Caller-supplied dedup token. Repeating it for the same org+SKU returns the existing subscription instead of starting a second one. Reactivating after a cancel needs a NEW value.

  • reason string Required

    Required audit reason — persisted on the BillingEvent

  • case string

    Case this add-on belongs to. Rentals are case-level; live banks may be org-level (omit).

  • startedAt string(date-time)

    When the subscription starts, ISO-8601. Defaults to now. Also the period anchor — every later period falls on this day-of-month, not the 1st.

Responses

  • 201 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • id string Required
      • organization string Required
      • case string | null Required
      • skuKey string Required

        Values are collection.phone, collection.social, collection.email, collection.ai-chat, collection.financial, collection.discord, collection.reddit, collection.linkedin, collection.legal, collection.file, collection.other, case.flat, case.pro-upgrade, addon.kit-rental, addon.laptop-rental, addon.laptop-rental-setup, addon.managed-service, addon.shipping, addon.live-bank, plan.base, source.per, ai.tokens-overage, adjustment.manual, or adjustment.discount.

      • recurrence string Required

        Values are monthly or semiannual.

      • startedAt string(date-time) Required

        Period anchor as well as the start date — every period falls on this day-of-month, not the 1st

      • canceledAt string(date-time) | null Required
      • status string Required

        Values are active or canceled.

      • externalRef string Required

        Caller-supplied dedup token

    • statusCode number Required
    • timestamp string(date-time) Required
POST /admin/orgs/{orgId}/recurring-addons 
curl \
 --request POST 'http://api.example.com/admin/orgs/{orgId}/recurring-addons' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "skuKey": "collection.phone",
  "externalRef": "string",
  "reason": "string",
  "case": "string",
  "startedAt": "2026-05-04T09:42:00Z"
}'
Request examples 
{
  "skuKey": "collection.phone",
  "externalRef": "string",
  "reason": "string",
  "case": "string",
  "startedAt": "2026-05-04T09:42:00Z"
}
Response examples (201) 
{
  "data": {
    "id": "65a1b2c3d4e5f6a7b8c9d0f1",
    "organization": "65a1b2c3d4e5f6a7b8c9d0e3",
    "case": "string",
    "skuKey": "addon.laptop-rental",
    "recurrence": "monthly",
    "startedAt": "2026-01-15T10:15:00.000Z",
    "canceledAt": "2026-05-04T09:42:00Z",
    "status": "active",
    "externalRef": "rental-2026-001"
  },
  "statusCode": 201,
  "timestamp": "2026-01-15T10:15:00.000Z"
}