Skip to main content
Tyms works with referral business partners (distributors): organizations or individuals who introduce small and medium-sized businesses in service, consulting, retail, and manufacturing to the platform. Partners may earn commissions or work on prepaid commercial terms on behalf of those businesses—commercial terms are agreed during partner onboarding with Tyms, not via this public API. This page explains the integration story. Request and response fields for each partner route are in API reference → Partners.

​
Becoming a partner

  1. Apply and onboard through Tyms’s partner program (sales or partner operations). Tyms registers you as a referral business partner and issues partner API credentials (partner secret key, often prefixed like adam_partner_sk_...).
  2. Agree commercial terms (revenue share, prepaid wallets, support expectations, branding, etc.). Those details are not exposed on the Developer API; they are contractual.
  3. Top up partner credit in the partner portal when you plan to grant Plus seats or transfer AI credits to referred businesses (see Covering costs).
  4. Integrate using your partner key for partner routes (register, list, billing, grants), then each business’s tyms_sk_... for day-to-day bookkeeping API calls.
Partner routes expect a partner credential (adam_partner_sk_...), not a business tyms_sk_ key. Send the partner secret in X-API-Key (or api-key / sk).

​
Why Register business exists

Partners often need to:
  • Create the Tyms business and owner account in one step.
  • Optionally become an admin on that business so they can finish setup or support the owner.
  • Optionally receive that business’s Developer API keys in the response so they can automate bookkeeping on behalf of the business they referred.
Only businesses created through this partner flow are attributed to you as referrer in Tyms’s systems. You receive api_secret_key in the success payload only when registration succeeds and you requested grant_access: admin (see reference).

​
Covering costs for referred businesses

After Tyms onboards you, you purchase partner credit into your holding balance (partner portal — not this API). That balance is what seat grants and credit transfers draw from. You resell or bundle access to businesses you referred however your commercial terms allow. When registering a business, credit_from_referral_partner (default false) controls who pays for ongoing AI usage:
Registration flagWhat it means
falseThe business has its own credit ledger. You grant Plus seats and/or transfer credits from your holding when you want to cover their costs.
trueTyms bills that business’s AI usage to your partner holding automatically. Seat and credit grant endpoints are blocked for that business — you are already managing usage centrally.
If credit_from_referral_partner is false, you have two ways to put value on a referred business from your holding: Use Add seats to activate Tyms Plus for a period and license a seat count. Tyms debits your holding at 150 credits × seats × months (150 AI credits per seat per month by default). The business receives matching AI credits on their ledger.
  • First call — starts Plus for the requested months (default 1) and sets seat count.
  • Later calls while that partner grant is still active — add seats for the remaining period only; holding cost and AI credits are prorated.
This is the approach we recommend: fixed seats, a clear subscription window, and predictable spend. The business can still cancel Plus from their own billing page; partner holding is not refunded.

​
Transaction credits (pay as you go)

Use Add credits to move AI credits from your holding to the business at 1:1 (100 holding credits → 100 usable AI credits). No Plus subscription required. Handy when plan-included credits run out, or when you prefer topping up usage instead of licensing seats. Transferred credits expire 12 months after the grant.
Seat grants and credit transfers only work for businesses you referred with credit_from_referral_partner: false. Check Billing status before granting, and List referred businesses to reconcile your portal.

​
End-to-end integration flow

1

Partner authentication

Obtain your partner secret from Tyms after partner onboarding. Use it for all routes under API reference → Partners (adam_partner_sk_... in X-API-Key, api-key, or sk).
2

Register the business

Register business — owner profile, business_name, password, optional locale fields, credit_from_referral_partner, and grant_access (admin | editor | viewer). On success you receive business_uuid; with grant_access: admin you also receive api_public_key and api_secret_key.
3

Grant Plus or credits (optional)

When credit_from_referral_partner is false, use Add seats to subscribe the business to Plus from your holding, or Add credits for a pay-as-you-go top-up. Billing status shows seats, plan, and credit balance before and after.
4

Integrate as the business

Call GET /auth/validate, POST /invoices, GET /reports/income-statement, etc., with X-API-Key: tyms_sk_... from the registration response — not the partner key.

​
API surface

All partner routes live on the same v1/adam base URL as the rest of the Developer API:
RoutePurpose
POST /register-businessCreate a referred business and optional admin API keys
GET /referred-businessesPaginated list of businesses you referred
GET /referred-businesses/{business_uuid}/billing-statusSubscription, seats, and credit snapshot for one business
POST /referred-businesses/{business_uuid}/add-seatsGrant or extend Plus seats from partner holding
POST /referred-businesses/{business_uuid}/add-creditsTransfer AI credits from partner holding (1:1)

​
Sandbox testing

Partners can exercise partner routes and subsequent business-scoped calls against the sandbox environment (https://staging-api.usetyms.com/v1/adam) before production. Email developer@usetyms.com for sandbox partner and business credentials — staging keys are separate from production partner secrets.

​
Support