Skip to main content

​
About

Read your organization’s plan, subscription dates, seat utilization, and credit balances. Check AI credit usage and low-balance warnings, look up fixed credit packs, and direct a human to the appropriate purchase page. All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

​
Operations

​
Subscription dates and seats

Use trialEnds to report when a trial ends and cancelAt to identify a scheduled cancellation. A deferred plan change appears in pendingPlanCode, pendingPlanIsAnnual, and pendingPlanEffectiveAt; until that date, planType is still the current plan. Those pending fields are null when no change is scheduled. isGrandfathered identifies a legacy price, and currentUnitAmountCents is the amount paid for the core plan. extraSeats.seatsCap is total capacity, including add-ons. Compare it directly with extraSeats.seatsUsed; do not add extraSeatQuantity again. featureLimits.seatsCap is only the plan’s included seats. A null unusedPaidSeats means the count is unknown, not zero; unusedPaidSeatsReleaseAt reports the scheduled release date when available. featureLimits.phoneNumbersCap and featureLimits.callingMinutesCap report the plan’s phone-number and calling-minute allowances. These fields describe allowances; they do not report current usage or prove that quota enforcement is enabled for your organization.

​
Credit packs

Quote top-ups from getCreditPrices.packs, using each pack’s units and total priceCents. Offer only rows with available: true; false means the Stripe price is unavailable or mismatched. Do not calculate a purchase quote from the legacy per-credit fields. Send getCreditsPurchaseUrl to the human who will complete the purchase.

​
Texting credits

creditLedger includes SMS_CREDITS, and featureLimits.smsCreditsCap is the plan’s included monthly texting-credit allowance. One credit equals one outbound carrier text segment; a multi-segment message consumes multiple credits. Inbound texts do not consume texting credits. Use the texting packs from getCreditPrices.packs to quote a top-up.

​
AI credit usage

getAiCreditUsage returns creditsConsumed, balanceCredits, and outOfCredits, plus lowOnCredits and lowCreditThresholdCredits. One AI credit represents one cent of AI cost. Balances may be negative; featureLimits.aiCreditsCap in the billing summary is the plan’s included monthly allowance. lowOnCredits: true is an early warning: the balance is still positive but at or below lowCreditThresholdCredits. It is mutually exclusive with outOfCredits; report the warning and threshold without claiming AI work has already stopped.
A false flag does not prove AI work can runoutOfCredits: true confirms the AI credit paywall. A gated organization with no prior AI usage can still have work refused at a zero or negative balance while this flag is false. Check balanceCredits as well; do not report that AI work can run from the flag alone. Use getCreditsPurchaseUrl to direct a human to top up.
The API never purchasesThere is no operation that buys credits or changes your plan. When a balance is low, send the user the URL from getCreditsPurchaseUrl — purchasing always happens in the app, by a person.
Which operations spend credits?Credit-spending operations require the ADMIN scope and are flagged on their own pages: enrichContact and createContactFromProperty (Contacts API), skipTraceProperty and manualSkiptrace (Properties API). Each consumes one skip-trace credit.
Scope-gated, org-scoped by your keyBilling operations take no cross-org ids, so there is no 403 forbidden here — every read is automatically scoped to your organization by the key. getBillingSummary requires the ADMIN scope; the rest are READ. See Authorization for the model.

​
Example

Check the skip-trace balance before a batch enrichment:
Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.