Create a connected account

A connected account contains the taxpayer's legal identity and address. For
ordinary sales, these details become the seller on its invoices. Create one
account per taxpayer VAT registration within your organization.

curl -X POST "$BASE/connected-accounts" \
  -H "Authorization: Api-Key $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example Trading",
    "tax_registration_number": "200007019800002",
    "business_category": "Retail",
    "identification": {"type": "SUBCRN", "value": "136690-1"},
    "street_name": "Road 2830",
    "block": "Block 428",
    "building_name": "Trade Centre",
    "flat": "388",
    "city": "Manama",
    "country": "BH"
  }'

The values above are examples; supply the taxpayer's actual registered details.
Store the response's id as ACCOUNT_ID for subsequent calls. All five address
fields shown above are required.

Choose how to onboard

Add an onboarding object to create and onboard in one request:

Value	Result
`{"mode":"DIRECT","otp":"<fresh-otp>","sub_cr":"<branch-sub-cr>"}`	Registers the taxpayer's own device using its NBR OTP.
`{"mode":"THIRD_PARTY"}`	Uses your provider organization's device. No supplier OTP is needed.
Omit `onboarding`	Creates a DIRECT account; register its device separately.

THIRD_PARTY registration requires complete provider identity and address on
PATCH /organizations/me. Configure the supplier's identification explicitly;
it does not come from the provider device or branch routing header. Register
the provider device before submitting
for delegated suppliers. The invoicing mode cannot be changed through PATCH.

List, update and remove accounts

Request	Purpose
`GET /connected-accounts`	List your accounts; use `page` and `page_size` for pagination.
`GET /connected-accounts/{id}`	Retrieve an account.
`PATCH /connected-accounts/{id}`	Update supplied profile fields.
`DELETE /connected-accounts/{id}`	Soft-delete the account and stop new submissions and pending retries.

Identity fields are protected while a DIRECT account has a COMPLIANCE or ACTIVE
device. Deactivate those devices before changing the certified identity.
identification, metadata and the optional PDF logo can be updated while
devices are active. A THIRD_PARTY supplier's VAT identity cannot be changed;
create a new account for a different taxpayer.

metadata is an optional JSON object for your own references. PATCH replaces
the object, and null clears it. Metadata is not sent to NBR; dates stored there
do not automatically expire authorization. Accepted documents remain available
after account deletion.