BigMindBigMindBigMind
Partner API
Sign inGet an API key
Partner API
OverviewAuthenticationCustomersPlansQuotesAccount & UsageBackup statusWebhooksError codesChangelog

Customers

Provision and manage end customers under your partner account. One call creates the customer, its organization and its plan, charges you, and (optionally) sends the welcome email — with the same rules, prices and outcomes as the portal.

What is charged, and when

  • Create: the first period's wholesale (what GET /v1/plans shows as wholesaleCost, times users, plus extra users) is charged to your credit at once. Nothing is charged if the request fails.
  • Free trial (trial: true): nothing now. The plan's first period is charged when the trial converts, 15 days later; a trial that is not funded then is suspended.
  • A bigger plan or more users: applied now, and charged the difference for the days left in the period (planChange.chargeNow).
  • A smaller plan, fewer users or a new billing cycle: nothing now. It is applied at the renewal (planChange.effectiveAt), and refused if the account would not fit the new plan.
  • Renewal: every period, on the renewal date, the plan's current wholesale is charged (webhook subscription.renewed), also while you have the customer suspended. When your credit cannot cover it the customer gets a grace period, then is suspended and scheduled for deletion (deletesOn; you are emailed the date); a top-up before that date reactivates it and cancels the deletion.
  • Suspend: nothing is refunded. A suspended customer is still renewed and charged at each renewal date, because its data is still stored, and reactivating it does not restart its billing period. If a renewal is unpaid when you reactivate, it is charged first (402 INSUFFICIENT_CREDITS if it cannot).
  • Delete: the unused part of the paid period comes back to your credit (refundAmount), at the prices the period was paid at.
  • Distributor-funded partners: every charge and refund above lands on your distributor's account instead of creditsBalance; a sale it cannot cover answers DISTRIBUTOR_ACCOUNT_LIMIT.
POST/v1/customers

Create a customer on a plan you sell, paid or on the free trial.

Request body

NameTypeDescription
emailrequiredstringCustomer email. Must be unique within your partner account.
namestring (2+ chars)Customer full name.
companyNamestringCustomer company / organization name.
phonestringCustomer phone number.
planIdrequiredstringA plan id from GET /v1/plans: planIds.monthly or planIds.yearly of a catalog plan, or the id of one of your own plans.
billingCycle"monthly" | "yearly"For your own plans, which carry no cycle in their id. A catalog id already says its cycle; Local DR is yearly only.
seatsinteger (1–1000)Users on a per-user plan (model per_user). Defaults to 1. Ignored on packages, which include their users.
extraUsersinteger (0–5000)Users above the ones a Vault, Local DR Plus/Pro or package plan includes, at the plan's extraUser price. Not for per-user plans.
trialbooleanStart the customer on the free trial: free for you, 15 days, a small whole-account storage allowance (10 GB hot + 1 GB cold, Home 5 GB). It converts to the plan when it ends and the plan is charged then. Not available on DR-Only, Local DR or BigMIND 1.0 plans; one per mailbox, with any partner (+tags are collapsed).
trialDaysinteger (0–90)Deprecated. Any value above 0 also starts the free trial; its length is always the standard one.
addOnsobjectLegacy per-customer extras on a catalog plan (see below). Your own plans carry their composition, so addOns on them answers CUSTOM_PLAN_ADDONS_FIXED.
sendWelcomeEmailbooleanSend branded welcome email to the customer. Defaults to true.
languagestring (max 10)ISO language code for emails and UI (e.g. "en", "es").
tagsstring[] (max 20)Tag ids (GET /v1/tags) to put on the new customer. Checked before anything is written: an unknown id is 404 TAG_NOT_FOUND and no customer is created.

Add-on units

NameTypeDescription
hotStorageGBintegerExtra hot storage in GB (canonical). e.g. 2000 = 2 TB.
hotStorageUnitsintegerLegacy: extra hot storage in 1 TB units (folded to GB). Prefer hotStorageGB.
hotStorage500GBUnitsintegerLegacy: extra hot storage in 500 GB blocks (folded to GB). Prefer hotStorageGB.
coldStorageUnitsintegerExtra cold storage. Each unit = 1 TB.
deepFreezeUnitsintegerExtra deep-freeze storage. Each unit = 1 TB.
extraServersintegerExtra server seats beyond plan.
mysqlDatabasesintegerMySQL backup databases.
mssqlDatabasesintegerMSSQL backup databases.
extraWorkspacesintegerNot sold: workspaces come with the plan (Standard 10, Pro unlimited). Send 0; a higher number is refused with EXTRA_WORKSPACES_NOT_SOLD.

Example

curl -X POST https://eu-bigmind2.genie9.com/api/partner/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "acme@example.com",
    "name": "Acme Co",
    "planId": "bigmind-standard-yearly",
    "seats": 5,
    "sendWelcomeEmail": true
  }'

Common error codes: VALIDATION_FAILED (400), INVALID_PLAN (404), PLAN_NOT_ENABLED (400 / 403), INSUFFICIENT_CREDITS (402), DISTRIBUTOR_ACCOUNT_LIMIT (400), CUSTOMER_EXISTS (409), CUSTOMER_DELETED_EMAIL_HELD (409), EMAIL_REGISTERED_AS_BIGMIND_USER (409), EMAIL_REGISTERED_WITH_OTHER_PARTNER (409), TRIAL_NOT_AVAILABLE (400), TRIAL_ALREADY_USED (409), TRIAL_LIMIT_REACHED (409), ENDED_TRIAL_EXISTS (409), FREE_ACCOUNTS_DISCONTINUED (400), TRIAL_EXPIRED (403), CANNOT_SELL (403). INSUFFICIENT_CREDITS carries required, current and a cost breakdown; nothing is written on any error. Two creates of one address at once: one answers 201, the other 409 CUSTOMER_EXISTS.

GET/v1/customers

List your customers, paginated and filterable.

NameTypeDescription
pageinteger ≥ 1Page number (1-indexed). Defaults to 1. 0, negative or non-numeric answers 400 VALIDATION_FAILED.
limitinteger (1–200)Items per page. Defaults to 20; outside 1–200 answers 400 VALIDATION_FAILED.
statusstringFilter by status: active, trial, suspended, trial_expired_suspended, trial_ended, inactive, cancelled, deleted. Any other value is a 400 VALIDATION_FAILED. Without status every customer except the deleted ones is listed (and counted in summary); status=deleted lists only the deleted ones.
planIdstring (max 100)Filter by plan ID.
searchstring (1–200)Partial match on email, name, or companyName.
tagstring, repeatableCustomers carrying this tag id. Repeat the parameter for "any of these tags" (?tag=a&tag=b).
renewingWithininteger (1–366)Active and trial customers whose renewal (or trial end) falls within this many days, overdue ones included.
sortBy, sortDirstringsortBy: name, companyName, email, status, createdAt or nextBillingDate; sortDir: asc or desc (the field's natural direction when omitted). Anything else is 400 INVALID_SORT. Without sortBy the newest customer comes first.

Monitoring fields on every row

Each customer row also carries these fields, so one paginated pass syncs your whole account base without a per-customer /usage or /devices call:

FieldTypeDescription
usedStorageGBnumberStorage counted against the customer's hot quota, in SI GB (2 dp): hot-tier files plus DR images and database backups; cold and deep-freeze tiers are not included. The same figure as GET /v1/customers/{id}/usage → storage.usedGB.
lastBackupAtISO 8601 | nullMost recent backup across the customer's devices, excluding deleted devices (GET /v1/customers/{id}/devices still lists deleted devices, so its newest lastBackup can be later). null if nothing has backed up yet.
subscriptionExpiresAtISO 8601 | nullEnd of the current period: for a trial customer the trial end, otherwise the date the next renewal is charged to your credits. null for plans that never renew. Meaningful for active and trial customers; a suspended or cancelled customer keeps its last value. Also returned by GET /v1/customers/{id}.
graceUntilISO 8601 | nullSet while a renewal could not be covered: the customer keeps working until this date unless you top up.
deletesOnISO 8601 | nullSet while the customer is suspended because a renewal could not be paid: the date its account and all its data are scheduled to be deleted (the date you were emailed). Paying the renewal before then reactivates it and cancels the deletion. Also returned by GET /v1/customers/{id}.
lastLoginAtISO 8601 | nullLast sign-in by the customer's owner account. null if nobody has signed in yet.
plan, metricsobjectplan: id, displayName (your name for it), customerPrice and billingCycle. metrics: monthlyValue (the customer's monthly retail; a yearly price counts one twelfth), recentCreditUsage (your spend on it in the last 30 days), isActive, daysAsCustomer.
tags, channelTrial, licencearray, object | null, object | nulltags: the customer's tags {id, name, color}. channelTrial: a running or ended free trial {source, endsAt, ended, deletesOn, converts, allowance, family}. licence: a licence-key customer {serialLast4, endsAt, ended, trialEndsAt, billingCycle, endedAt, endReason}. The same objects GET /v1/customers/{id} returns.

The summary object

summary describes every customer the filters (status, planId, search) match, not only the returned page. It is cached for up to 60 seconds; changes made through the API or the portal refresh it at once.

FieldTypeDescription
totalCustomersintegerCustomers the filters match.
activeCustomers, billingActiveCustomers, expiredCustomersintegeractiveCustomers: status active and the service has not expired. billingActiveCustomers: status active, expired services included. expiredCustomers: the difference.
inactiveCustomersintegerCustomers with status inactive, cancelled, suspended, trial_expired_suspended or trial_ended.
activeInUseCustomersintegeractiveCustomers minus neverUsedCustomers: status active, a service that has not expired, and signed in or data stored. The portal's Active Rate is this divided by totalCustomers.
trialCustomersintegerCustomers with status trial.
neverUsedCustomersintegerCustomers with status active that have never signed in and have no data stored. They are counted in billingActiveCustomers, not in inactiveCustomers.
totalRevenue, averageRevenuePerCustomer, activeCustomersWithoutRetailPricenumber | nullMonthly retail revenue of the active customers (a yearly price counts one twelfth). Customers with no retail price are counted in activeCustomersWithoutRetailPrice and left out of the total and the average. null when revenueUnavailable is set.
recentCreditUsageTotal, averageRecentCreditUsagenumberCredits used in the last 30 days by these customers: the total, and the total divided by totalCustomers.
revenueUnavailableobject | nullnull, or why revenue was not computed: REVENUE_SCAN_CAP_EXCEEDED when more than 10,000 customers have status active.
curl -H "Authorization: Bearer sk_live_..." \
  "https://eu-bigmind2.genie9.com/api/partner/v1/customers?status=active&limit=50"
GET/v1/customers/{id}

Get a single customer with its plan and price, the running trial or grace period, full billing config, credit history, and recent support tickets.

curl -H "Authorization: Bearer sk_live_..." \
  https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_1759590000000_a1b2c3d4

Returns CUSTOMER_NOT_FOUND (404) if the customer doesn't belong to your partner account. billingConfig.pendingChange holds a change waiting for the renewal (plan, cycle, users, effectiveAt).

PATCH/v1/customers/{id}

Change the plan, users or billing cycle with the same rules as the portal: a bigger plan or more users applies now and is charged prorated for the rest of the period; a smaller plan, fewer users or a new cycle waits for the renewal, and is refused if the account would not fit. The response carries the outcome in planChange.

NameTypeDescription
namestringUpdate customer display name.
companyNamestring
phonestring
planIdstringMove to another plan you sell (catalog or your own).
seatsintegerUsers on a per-user plan.
extraUsersintegerUsers above the ones a package or Vault plan includes, at your extra-user price.
billingCycle"monthly" | "yearly"Takes effect at the renewal. On a catalog plan it moves the customer to the plan's other-cycle id (INVALID_PLAN if the plan is not sold on that cycle); on your own plan it changes the cycle.
addOnsobjectLegacy per-customer add-ons on a catalog plan, charged prorated now. A request carrying addOns takes the legacy path and its planId / seats follow the legacy rules; extraUsers and billingCycle are not applied on it.
languagestringUpdate customer language.

Every change is priced and charged (or scheduled) by the rules above. The former calculateProrating flag is accepted and ignored.

A customer on a free trial, a free account or a BigMIND 1.0 plan keeps the Edit dialog's rules: planId and seats are applied the legacy way, and extraUsers or billingCycle answer 400 VALIDATION_FAILED rather than being dropped.

curl -X PATCH https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "seats": 8 }'

The planChange object

FieldTypeDescription
timing, reasonstringtiming: now (applied and charged), renewal (recorded as pendingChange, applied on effectiveAt) or none (nothing changed). reason: increase, decrease, cycle or same.
chargeNownumberWhat was charged to your credit now: the difference between the new and the current daily wholesale, times daysRemaining. 0 when the change waits for the renewal.
current, nextobjectThe plan as paid for this period and the plan asked for: planId, planName, billingCycle, users, includedUsers, extraUsers, retail (the customer's price per period) and wholesale (yours).
capacityobjectok, and problems[] with kind (users, hot, cold, deep_freeze), used and limit. A change that does not fit is refused with CAPACITY_EXCEEDED carrying the same problems.

Error codes: VALIDATION_FAILED (400), INVALID_PLAN (404), PLAN_NOT_ENABLED (400 / 403), CAPACITY_EXCEEDED (400), INSUFFICIENT_CREDITS (402), DISTRIBUTOR_ACCOUNT_LIMIT (400), CUSTOMER_CHANGED (409), PLAN_SEATS_FIXED (400), CUSTOM_PLAN_ADDONS_FIXED (400), SEATS_BELOW_USAGE (400), BM1_SUBSCRIPTION_IMMUTABLE (400), FORBIDDEN (400). CUSTOMER_CHANGED means another request changed the customer first: nothing was written or charged, read it again and retry.

DELETE/v1/customers/{id}/pending-change

Cancel the change waiting for the renewal (a smaller plan, fewer users or a new cycle asked for earlier). The customer stays on its current plan; nothing is charged or refunded.

curl -X DELETE https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_.../pending-change \
  -H "Authorization: Bearer sk_live_..."

Idempotent: with nothing waiting, cancelled is false. The waiting change is visible as billingConfig.pendingChange on GET /v1/customers/{id}.

POST/v1/customers/{id}/suspend

Reversibly suspend a customer. They keep sign-in and read access to their data; backups, restores and downloads are refused until reactivated. No data is deleted, no refund issued. The customer is still renewed and charged at each renewal date while it is suspended.

curl -X POST https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_.../suspend \
  -H "Authorization: Bearer sk_live_..."

Idempotent — re-suspending a suspended customer is a no-op. A deleted customer answers 400 FORBIDDEN. A running free trial can be suspended; reactivating it resumes the trial (status trial), it does not become a paid customer.

POST/v1/customers/{id}/reactivate

Reverse a suspension. Inside a paid period nothing is charged; after the period ended, the overdue renewal is charged first. Cannot reactivate deleted customers.

curl -X POST https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_.../reactivate \
  -H "Authorization: Bearer sk_live_..."

Errors: 402 INSUFFICIENT_CREDITS (details.reason REACTIVATE_NEEDS_CREDIT, required, current) when the overdue renewal cannot be covered — a top-up reactivates the customer by itself; 400 FORBIDDEN for a deleted customer, an ended trial or an ended licence; 409 VALIDATION_FAILED (details.reason COST_UNRESOLVED) when the renewal cannot be priced. 409 CUSTOMER_CHANGED when the customer changed while the request ran: read it again and retry.

POST/v1/customers/{id}/extend-trial

Extend a free trial that has ended (only on installations that let an address sign up again). The trial runs again from today for `days` days, a whole number from 1 to the trial length, as often as you like; it counts towards your running-trial limit. To keep the data after that, upgrade the customer to a paid plan.

curl -X POST https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_.../extend-trial \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "days": 7 }'

Errors: 403 TRIAL_EXTENSION_UNAVAILABLE where extensions are not offered; 409 TRIAL_NOT_EXTENDABLE when the trial has not ended (details.reason NOT_ENDED) or was closed because its address signed up again (CLOSED); 400 VALIDATION_FAILED for days outside 1 to the trial length; 409 TRIAL_LIMIT_REACHED when your running trials are at the limit; 409 CUSTOMER_CHANGED when the customer changed while the request ran.

DELETE/v1/customers/{id}

Soft-delete the customer. Suspends their organization, revokes access tokens, cancels the subscription, and refunds the unused part of the paid period to your credit (or to your distributor's account).

curl -X DELETE https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_... \
  -H "Authorization: Bearer sk_live_..."

refundAmount is the unused days of the current period at the prices it was paid at (a trial customer: 0). emailReleased says whether the address can be used for a new customer at once: true when the account never held data; false when backups are kept, in which case re-creating on that address answers CUSTOMER_DELETED_EMAIL_HELD. A second DELETE answers 400 FORBIDDEN (details.reason CUSTOMER_DELETED) and refunds nothing.

POST/v1/customers/{id}/send-welcome

Resend the branded welcome email to an active or trial customer. At most once per customer every 10 minutes (429 RATE_LIMITED with details.retryAfterSeconds); a suspended, ended or deleted customer answers 400 FORBIDDEN.

curl -X POST https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_.../send-welcome \
  -H "Authorization: Bearer sk_live_..."

Tags

Your own labels on your customers — a segment, a site, a contract type, a PSA company id. Up to 250 tags per partner (names unique, 60 characters), up to 20 on one customer. A tag id that is not yours is 404 TAG_NOT_FOUND and nothing is linked.

GET/v1/tags

List your tags with how many customers carry each. ?search= matches the name; page / limit as everywhere.

curl -H "Authorization: Bearer sk_live_..." "https://eu-bigmind2.genie9.com/api/partner/v1/tags?search=vip"
POST/v1/tags

Create a tag: { name, color? }. 409 TAG_EXISTS for a name you already use; 400 TAG_LIMIT_REACHED at 250.

curl -X POST https://eu-bigmind2.genie9.com/api/partner/v1/tags \
  -H "Authorization: Bearer sk_live_..." -H "Content-Type: application/json" \
  -d '{ "name": "VIP", "color": "#f00" }'

PATCH /v1/tags/{id} renames or recolours; DELETE /v1/tags/{id} removes the tag from every customer and answers how many were untagged.

PUT/v1/customers/{id}/tags

Replace the customer's tag set: { tagIds: [...] }. GET returns it. POST /v1/customers/{id}/tags/{tagId} adds one and DELETE …/tags/{tagId} removes one; both are idempotent and answer the tag list.

curl -X PUT https://eu-bigmind2.genie9.com/api/partner/v1/customers/pc_42_.../tags \
  -H "Authorization: Bearer sk_live_..." -H "Content-Type: application/json" \
  -d '{ "tagIds": ["cmuu0gwzl002x"] }'
GET/v1/customers/{id}/usage

Storage used / quotas / device + file counts for a single customer.

{
  "success": true,
  "data": {
    "customerId": "pc_42_...",
    "storage": {
      "usedGB": 214.5,
      "hotQuotaGB": 2500,
      "coldQuotaGB": 2000,
      "deepFreezeQuotaGB": 0
    },
    "deviceCount": 8,
    "fileCount": 124803
  }
}

deviceCount and fileCount are the live inventory: deleted devices and files in the trash are not counted. The quotas are the plan's: per-user plans give hot storage per user times users; a Vault 10 TB is 1,500 GB hot plus 8,500 GB cold. GET /v1/plans shows the same figures under includes.

GET/v1/customers/{id}/devices

List the customer's backup devices (read-only), newest backup first, page / limit (default 50, max 200). Each row carries the device's health — agentVersion, lastSeenAt, online, lastBackupAt, lastBackupStatus, lastSuccessfulBackupAt, consecutiveFailures — explained on the Backup status page.

{
  "success": true,
  "data": {
    "devices": [
      {
        "id": "bd_...",
        "name": "DESKTOP-ACME-01",
        "platform": "windows",
        "status": "active",
        "lastBackup": "2026-05-12T18:42:11.000Z",
        "createdAt": "2026-04-02T10:11:30.000Z",
        "agentVersion": "2.14.3",
        "lastSeenAt": "2026-05-12T18:59:51.000Z",
        "online": true,
        "lastBackupAt": "2026-05-12T18:52:03.000Z",
        "lastBackupStatus": "completed",
        "lastSuccessfulBackupAt": "2026-05-12T18:52:03.000Z",
        "consecutiveFailures": 0
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 1, "pages": 1 }
  }
}