API reference

Entities

Read and manage companies (entities) provisioned through FTA onboarding. Your application reaches every entity its owner can reach in the Tax Star E-Invoice application — the ones they own or are a member of — automatically. There is nothing to connect. What it may do on each follows the owner's role there: an Editor's app has full access except deleting the entity; an Approver's or Viewer's app is read-only. Every entity in GET /oauth/entities carries an access block saying which. See Roles and permissions for the full rules. Requires an access token.

GET/oauth/entitiesAccess token

List entities

Return every entity your application can reach: owned by the app's owner or shared with the owner by invitation. Each entity carries access: { role, via, can_write, can_delete }. role is admin, editor, approver or viewer; via is owner (the owner's own entity) or member (shared with the owner). users_access, the list of who has access, is filled in only where role is admin or editor; for an approver's or viewer's entity it is an empty list. Pass user_id to return only the entities owned by a specific user. Paged: page (default 1) and limit (default 20, at most 100); the response carries pagination: { total_data, total_page, page, limit } — keep requesting pages until page reaches total_page. search narrows to entities whose company name or TRN contains the text.

Query parameters

`user_id`	Only entities owned by this user of your app.
`page`	Page number. Defaults to 1.
`limit`	Entities per page, 1-100. Defaults to 20.
`search`	Only entities whose company name or TRN contains this text.

GET/oauth/entities/{entity_id}Access token

Get an entity

Fetch a single entity your application can reach, with the same access block as GET /oauth/entities. users_access (who has access) is filled in only for an admin's or editor's app, and empty for an approver's or viewer's. An entity the app cannot reach answers 404, the same as one that does not exist.

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, 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. Needs admin or editor access to the entity; an approver's or viewer's app gets 403.

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"
}

Responses

200	Entity updated successfully
403	Your role on this entity is read-only (approver or viewer)
404	Entity not found, or not reachable by this application

POST/oauth/entities/{entity_id}/membersAccess token

Invite a member

Invite someone to the entity by email, with the role editor, approver or viewer — the same invitation an Admin or Editor sends from the User Access panel in the Tax Star E-Invoice application, with the same email and link. Admin is never offered, as in the application. The link is valid for 24 hours. An approver joins without a TaxStar account by accepting on the confirmation page, and from then on is emailed every invoice of this entity that waits for approval — this is how an integration appoints the approvers for Require Approval for Sending. An editor or viewer with no account gets one when they accept (creates_account: true); one who already has an account signs in and opens the link. Needs admin or editor access to the entity. The response carries invitation: { id, email, role, status, creates_account, created_at, expires_at }. The address is stored lower-cased.

Request body example

{
  "email": "approver@example.com",
  "role": "approver"
}

Body parameters

`email`	string	optional	Who is invited. The invitation link is emailed to this address.
`role`	string	optional	One of "editor", "approver" or "viewer". See Roles and permissions for what each may do.

Responses

201	Invitation sent; the body carries the invitation
400	Invalid email or role (admin is not offered), or the address already has access
403	Your role on this entity is approver or viewer
404	Entity not found, or not reachable by this application

GET/oauth/entities/{entity_id}/membersAccess token

List members and invitations

Who has access to the entity and who is invited but has not accepted yet. members is a list of { email, role, added_at }; invitations is a list of { id, email, role, status, creates_account, created_at, expires_at }, where status is pending or expired. An accepted invitation moves to members; a revoked one disappears. Needs admin or editor access, as in the application — the list names other people, so an approver's or viewer's app gets 403.

Responses

200	Members and outstanding invitations
403	Your role on this entity is approver or viewer
404	Entity not found, or not reachable by this application

DELETE/oauth/entities/{entity_id}/members/invitations/{invitation_id}Access token

Revoke an invitation

Withdraw an invitation that has not been accepted; its link stops working. Use the id from the invite response or from the list. An invitation that was already accepted is a membership and answers 404 here. Needs admin or editor access to the entity.

Responses

200	Invitation revoked
403	Your role on this entity is approver or viewer
404	Entity not found, or no pending invitation with this id on it

PreviousUsers NextInvoices