API reference

Entities

Register and manage companies (entities) that will send invoices. You can create new entities directly via the API, or connect entities you already have in the Tax Star E-Invoice application. Each entity is owned by a user of your application. Requires an access token.

POST/oauth/entities/connectAccess token

Connect an existing entity

Connect a company you already registered in the Tax Star E-Invoice application to this OAuth app. The entity must be owned by the same account that owns your application — find your entity IDs on the entity details page at einv.taxstar.app. After connecting, the entity appears in GET /oauth/entities and can be used as entity_id in all invoice API calls. This operation is idempotent — calling it again on an already-connected entity returns success.

Request body example

{
  "entity_id": "64a1b2c3d4e5f6g7h8i9j0k1"
}

Body parameters

entity_id string required The ID of an existing entity in the Tax Star platform. Find it on the entity details page in the E-Invoice app.In the PINT XML Not emitted. Connecting an entity is what lets you invoice from it — every seller element on a later invoice (cac:AccountingSupplierParty) is then read from that entity record.

POST/oauth/entitiesAccess token

Create an entity

Register a new company directly through the API. TRN must be exactly 15 characters and unique, and it must be a conformant UAE TRN — 15 digits, starting with "1" and ending with "03" — because it is emitted as the seller VAT identifier (IBT-031, cac:PartyTaxScheme/cbc:CompanyID) on every invoice sent for the entity. A TRN outside that shape is accepted here but every send for the entity then fails validation with a seller_party error (ibr-132-ae), so fix it before sending. Omit user_id and the entity is owned by the application owner (the default — you create the entity for yourself). To create the entity on behalf of one of your users, set user_id to that user's id (from POST /oauth/users); it must belong to this same application.

Request body example

{
  "company_name": "ABC Corporation",
  "trn": "123456442311611",
  "country": "United Arab Emirates",
  "state": "Dubai",
  "city": "Dubai",
  "area": "Downtown",
  "postal_code": "12345",
  "mobile": "+971501234567",
  "landline": "+97143210000",
  "email": "info@abccorp.com",
  "email_notifications_enabled": true,
  "legal_registration_type": "TL",
  "legal_registration_id": "2309778",
  "issuing_authority": "Department of Economic Development - Dubai",
  "user_id": ""
}

Body parameters

`legal_registration_id`	string	optional	The entity's legal registration number (IBT-030) — trade licence, Emirates ID, passport or cabinet-decision number, whichever legal_registration_type says it is. Stored on the entity for your records and for the ERP-driven flows. NOTE: it is NOT emitted on invoices sent through this API. The seller's Peppol identity is what goes into cac:PartyLegalEntity/cbc:CompanyID on a sent invoice: the entity's registry code, qualified schemeID="0235", schemeAgencyID="PAS", schemeAgencyName="AE". Billberry resolves the sending organization from that element, and a document carrying anything else there is rejected with 403 "Invoice Not From A Partner's Organization".In the PINT XML Not emitted. On this API cac:PartyLegalEntity/cbc:CompanyID always carries the entity's registry code instead — verified on a generated document. The field still applies to the ERP-driven flows.
`legal_registration_type`	string	optional	Which kind of registration legal_registration_id is, emitted as its @schemeAgencyID (BTUAE-15). One of "TL" (Commercial/Trade license), "EID" (Emirates ID), "PAS" (Passport) or "CD" (Cabinet decision) — any other value is rejected with a 400. ibr-173-ae (fatal) requires one of these whenever the identifier is present, the electronic-address scheme is "0235" and the seller country is AE, so set it for AE sellers. Blank keeps the previous behaviour: "TL" when a registration number is on file.In the PINT XML Not emitted. On this API @schemeAgencyID is always "PAS", whatever you store here. It does apply to the ERP-driven flows.
`issuing_authority`	string	optional	The authority that issued the registration (BTUAE-12), emitted as @schemeAgencyName. Applies to "TL", "EID" and "CD". Blank for a trade licence falls back to the generic "Trade License issuing Authority" label; blank for the others emits no @schemeAgencyName at all.In the PINT XML Not emitted. On this API @schemeAgencyName is always "AE". It does apply to the ERP-driven flows.
`passport_country`	string	optional	The country that issued the passport (BTUAE-18), as a two-letter code, emitted as @schemeAgencyName in place of issuing_authority when legal_registration_type is "PAS".In the PINT XML Not emitted. Same @schemeAgencyName, always "AE" on this API.
`trade_license_number`	string	optional	The former name of legal_registration_id, from when a trade licence was the only registration an entity could carry. Still accepted and still read, so nothing breaks — but send legal_registration_id + legal_registration_type on new integrations.In the PINT XML Not emitted. Same as legal_registration_id — the registry code wins on this API.

GET/oauth/entitiesAccess token

List entities

Return all entities connected to your application — both created via the API and connected from the Tax Star platform. Pass user_id to return only the entities owned by a specific user.

GET/oauth/entities/{entity_id}Access token

Get an entity

Fetch a single entity connected to your application.

PATCH/oauth/entities/{entity_id}Access token

Update an entity

Update one or more fields of an entity. Send only the fields you want to change — any field of POST /oauth/entities is accepted, including the legal-registration group (legal_registration_id, legal_registration_type, issuing_authority / passport_country), which is how you change the seller identity that goes out on this entity's invoices.

Request body example

{
  "city": "Abu Dhabi",
  "email": "billing@abccorp.com",
  "legal_registration_type": "EID",
  "legal_registration_id": "784-1990-1234567-1",
  "issuing_authority": "Federal Authority for Identity and Citizenship"
}

DELETE/oauth/entities/{entity_id}/disconnectAccess token

Disconnect an entity

Remove the OAuth application link from an entity. The entity remains in the Tax Star platform but is no longer accessible via this application's API. Use this for entities that were connected (not created) via the API. To permanently remove an entity use DELETE /oauth/entities/{entity_id}.

DELETE/oauth/entities/{entity_id}Access token

Delete an entity

Permanently soft-delete an entity created by your application. For entities that were connected (not created) via the API, use /disconnect instead to preserve the entity in the platform.

PreviousUsers NextInvoices