BillOS v1
Console llms.txt OpenAPI
POST/businesses/{bid}/ita/connect

Start a consent

POST /businesses/{bid}/ita/connect

Requires the businesses scope.

Returns an address for the business's OWNER to open. Live, it is the רשות המסים consent page: he signs in there with his own credentials and authorizes BillOS to request allocation numbers for his business. In the sandbox it is a simulated consent page and nothing reaches the authority.

Afterwards his browser lands on returnUrl with ita (connected, denied or error), business, your state, and on a failure reason. Treat that query as a hint and confirm with GET /businesses/{bid}/ita or the ita.connected webhook.

returnUrl is not registered ahead: it must be https (http to localhost in the sandbox), carry no credentials or fragment, and not already use the names BillOS adds. Owner only; the business must be approved and not paused.

Path parameters

NameTypeDescription
bidstringrequiredBusiness id, from POST /businesses.

Body

FieldTypeDescription
returnUrlstringrequiredWhere the owner lands after the consent. Up to 512 characters.
statestringYour own value, echoed back on returnUrl. Printable ASCII, no spaces, up to 128 characters. Use it to tie the return to your user's session.
linkbooleanTrue for an address to SEND the owner (by email or WhatsApp), good for 24 hours. Default: 15 minutes, for a user who is in front of your screen now.

Response

201: { "ok": true, … }

FieldTypeDescription
okbooleanrequired
urlstringrequiredThe address the owner opens.
expiresAtstringrequiredAfter this the address no longer works: start a new one.
sandboxbooleanrequired

Errors: 400, 401, 403, 404, 429, 503. Every failure answers { "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }: branch on reason, and read hint for what to change (https://docs.billos.co.il/errors.md).

PreviousRemove the connection NextMove a sandbox connection in time
On this page
Path parametersBodyResponse
POST /businesses/{bid}/ita/connect 
curl -X POST "$BASE/businesses/$BID/ita/connect" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "returnUrl": "string"
  }'
const res = await fetch(`${BASE}/businesses/${BID}/ita/connect`, {
  method: 'POST',
  headers: {
    'X-Api-Key': KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "returnUrl": "string"
  }),
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
import requests
res = requests.post(
    f"{BASE}/businesses/{BID}/ita/connect",
    headers={"X-Api-Key": KEY},
    json={
      "returnUrl": "string"
    },
)
data = res.json()
Set BASE to https://api.billos.co.il/v1 and KEY to your bk_live_… key, or a bk_test_… key to run it against the sandbox.
Manage your businesses, keys and webhooks in the BillOS Console.