Onboard a Business

Guide

For a platform on the API plan: a SaaS that issues tax documents for its customers, with Glance as the engine. Every customer becomes a business of your developer account, with its own Tax Authority connection, API keys and document numbering, and your account's tier covers them all. You call the /platform routes with an owner key of your developer account, and issue documents with each business's own key.

1. Create the Business

When a customer signs up with you, open a business for it with its name, Israeli business id and dealer type. If it is moving from other software, pass its starting numbers in the same call (see step 3).

curl -X POST https://api.glance.co.il/platform/businesses \
  -H "Authorization: Bearer $GLANCE_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "סטודיו לוטם",
    "taxId": "514000003",
    "type": "COMPANY",
    "email": "billing@lotem.example",
    "startingNumbers": { "invoiceReceipt": 1001 }
  }'

{
  "business": {
    "id": "7c1e2a90-4b6d-4f1e-9a3b-2d5f8e0c1a77",
    "name": "סטודיו לוטם",
    "taxId": "514000003"
  },
  "apiKey": "gk_live_9b2f4c7e1a3d5f8b0c2e4a6d8f1b3c5e7a9d2f4b6c8e0a1c3e5f7b9d1a3c5e7f",
  "numbering": {
    "invoiceReceipt": {
      "status": "set",
      "start": 1001
    }
  },
  "taxAuthorityConnect": {
    "url": "https://app.glance.co.il/connect/tax-authority?token=eyJhbGciOi…",
    "expiresAt": "2026-11-14T09:30:00.000Z"
  }
}

A business id that is already on Glance answers 409 COMPANY_EXISTS. Past the trial allowance of three businesses, or after the trial, the account needs a payment method first — 402 API_BILLING_METHOD_REQUIRED.

2. Store the Key

Save business.id and apiKey against your customer record, the key in your secrets store. The key is shown only in this response — afterwards Glance returns only its last four characters. Lost it? Issue a new one with POST /platform/businesses/:id/keys and revoke the old one.

The key is an editor key of that business, which may also manage the business's own webhooks. It can only ever act for that one business, so a bug in one customer's integration cannot touch another's documents.

3. Set the Starting Numbers

Every business numbers its documents on its own, starting at 1 for each type. A customer coming from other software usually has to continue its sequence — the next invoice-receipt after 1000 must be 1001. Set where each tax document type starts, either in startingNumbers when you create the business, or afterwards with PUT /platform/businesses/:id/numbering:

PUT /platform/businesses/7c1e2a90-4b6d-4f1e-9a3b-2d5f8e0c1a77/numbering
Content-Type: application/json

{
  "startingNumbers": {
    "invoice": 1001,
    "receipt": { "start": 500, "prefix": "R-", "paddingLength": 6 }
  }
}

The keys are invoice, invoiceReceipt, receipt and refund (credit note). Numbering must stay continuous, so a type can only be set before its first document of the year; after that the response reports it as locked and leaves it as it is. Set the numbers before the first document is issued. The business can do the same with its own key through POST /counters/create.

4. Send the Tax Authority Connect Link

Allocation numbers are requested on the business's own authorization at the Israel Tax Authority, and only the business owner can grant it — by logging in to the Tax Authority with their own credentials. Neither you nor Glance can do it for them, and the owner does not need a Glance login. Every business connects on its own — one owner's authorization never covers another business. That is what the hosted connect link is for:

1. Send taxAuthorityConnect.url to the owner — by email, or behind a “Connect to the Tax Authority” button in your product.
2. The owner opens it and sees the business name on a Glance page.
3. They log in to the Tax Authority and approve.
4. They land back on a confirmation page. The business is connected.

A link is valid for 7 days. If it expires unused, request a fresh one with POST /platform/businesses/:id/tax-connect-link. Follow the result in taxAuthority.connected on the business, and send a new link ahead of taxAuthority.expiresAt, when the authorization itself runs out.

5. Issue Documents With the Business's Key

Everything you do for a customer — clients, documents, webhooks — goes through that business's key, never the platform key. The routes are the regular Documents API, limited to the four tax document types:

curl -X POST https://api.glance.co.il/documents/create/invoiceReceipt \
  -H "Authorization: Bearer $CUSTOMER_GLANCE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10482" \
  -d '{
    "client": { "name": "דנה כהן", "email": "dana@example.com" },
    "identifyClientBy": "email",
    "products": [{ "description": "Monthly subscription", "units": 1, "price": 120 }],
    "payments": [{ "amount": 141.6, "paymentMethod": "creditCard", "date": "2026-11-07" }],
    "sendToClient": true
  }'

Register webhooks per business with the same key so each customer's events reach you tagged by business. Use Idempotency-Key on every create: a retried request then never issues — or bills — a document twice.

6. Monitor Usage

GET /platform/account returns this month's connected businesses against your tier and the estimated charge. GET /platform/businesses lists every business with the documents it issued and its Tax Authority connection — enough to bill your own customers and to spot one whose connection is about to expire. Both take ?month=YYYY-MM for an earlier month.

7. Change the Tier

PUT /platform/tier
Content-Type: application/json

{ "tier": "growth" }

The tier is the account's, not a business's. The change is immediate, up or down, and the tier the account is on when its month is billed sets the whole month's fee and included businesses — so when you pass a tier's included number, moving up before the 1st is usually cheaper than paying for the extra businesses.

8. Close the Business

When a customer leaves, DELETE /platform/businesses/:id. Its keys stop working immediately. It still counts as connected for the current month, and not for the next. Its documents are kept, as the record-keeping rules require.