Partner overview

What it is

Bring your own clients to Tax Star. Pre-register each one by its TIN; when its company is on the platform you are linked to it and added as an editor, so your application can manage it.

Who it is for

Any approved OAuth app with the full API. There is nothing to apply for.

What you get

Editor access to every company linked to you, and its sent, received and failed counts.

Resellers use a parallel flow with the same rules, on the Reseller API page. A person who is both has one list in each, and neither sees the other's.

You see only the clients you pre-registered yourself, never another partner's or reseller's. The endpoints are on Partner clients in the API reference.

Four steps. The fourth is optional.

1. 1

   Step 1: Get an access token

   Exchange your app's client_id and client_secret. Create the app on Create an app if you have none.

   POST /oauth/token

   Copy

   curl -X POST https://api.taxstar.app/einv/oauth/token   -H "Content-Type: application/json"   -d '{
       "grant_type": "client_credentials",
       "client_id": "tsk_...",
       "client_secret": "tsec_..."
     }'
   # Use the access_token it returns as: Authorization: Bearer <access_token>

2. 2

   Step 2: Pre-register a client

   Send its 10-digit tin and email. A 201 means it is stored, and linked_existing_entity says whether it was linked at once.

   POST /oauth/partners/pre-register

   Copy

   curl -X POST https://api.taxstar.app/einv/oauth/partners/pre-register \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "tin": "1000000000",
       "email": "client@example.com",
       "company_name": "Client LLC"
     }'

3. 3

   Step 3: Read its status

   pending until a company with that TIN is registered, then entity_created with its counts.

   GET /oauth/partners/pre-register/clients

   Copy

   curl https://api.taxstar.app/einv/oauth/partners/pre-register/clients?status=pending   -H "Authorization: Bearer $ACCESS_TOKEN"

4. 4

   Step 4: Optional: get told when it happens

   Subscribe to client.onboarded instead of polling. Skip this step and the status above still works.

   POST /oauth/webhooks

   Copy

   curl -X POST https://api.taxstar.app/einv/oauth/webhooks \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/taxstar/webhooks",
       "events": ["client.onboarded"]
     }'

Pre-registering tells Tax Star which company you are bringing: its TIN, and the email of the person to reach. Do it with POST /oauth/partners/pre-register, before or after the company is on the platform. You then see when each client is onboarded and follow its activity as counts.

The partner and reseller flows are the same, with separate lists: what you pre-register here is never shown to the other, even when one person holds both.

One flow, two kinds of access. The difference is what a link gives you, and it is the same table on both pages.

From your request to the link and what follows it. A request gets exactly one of the outcomes below.

A client's status is one of two words, and a refused request is never stored.

Seven steps, and who does each: you, Tax Star, or the company's owner.

1. 1

   YouPre-register the client

   Send the client's TIN (10 digits) and email, with an optional company name and notes.

2. 2

   Tax StarChecks the TIN

   No company yet: your request waits (pending). A company already registered with nothing attached: linked at once. Something attached: refused with 409.

3. 3

   Tax StarLinks the company

   Now, or later when a company registers with that TIN. The request becomes entity_created, and the entity is marked as yours.

4. 4

   Company ownerIs told by email

   Tax Star emails the owner (the partner email), names you, and asks them to contact support if they did not allow it.

5. 5

   Tax StarAdds you as an editor

   Your account joins the company's members as an editor. An existing role is kept, an owner is not added, and the owner can remove you.

6. 6

   Tax StarSends client.onboarded

   To your webhook, if you subscribed. Up to about a minute later, retried up to 8 times.

7. 7

   YouManage the company and follow its counts

   Use the company through your application as an editor, and read sent, received and failed counts from the client list.

Keep the first ten digits of the company's TRN. That is the TIN, and it is the only identifier this API takes.

Each request has exactly one outcome. The 201 outcomes store a client. A 409 tin_reserved means another partner or reseller requested the TIN first.

Nothing attached means no reseller, no partner and no OAuth application is connected to the company. If the company is already registered, the first requester gets it: the link is made in a single step, so a second request is refused. A refusal never says who holds the company.

What a link gives. A partner is added to the company's members as an editor, at once, in both linked cases. A role you already hold is left as it is, and a partner that owns the company is not added.

The request is the same for every outcome. Replace ACCESS_TOKEN with a token from POST /oauth/token; the values below are fake.

curl -X POST https://api.taxstar.app/einv/oauth/partners/pre-register \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "1000000000",
    "email": "client@example.com",
    "company_name": "Client LLC"
  }'

201: no company yet. The request waits. activity is null until a company exists.

{
  "message": "Client requested",
  "linked_existing_entity": false,
  "client": {
    "id": "6710c0ffee0000000000abcd",
    "tin": "1000000000",
    "email": "client@example.com",
    "company_name": "Client LLC",
    "notes": "",
    "status": "pending",
    "created_at": "2026-10-01T09:00:00+00:00",
    "entity_created_at": null,
    "activity": null
  }
}

201: already registered, nothing attached. Linked at once. The message reads “This company is already registered and nothing else was attached to it, so it has been linked to you”.

{
  "message": "This company is already registered and nothing else was attached to it, so it has been linked to you",
  "linked_existing_entity": true,
  "client": {
    "id": "6710c0ffee0000000000abce",
    "tin": "1000000000",
    "email": "client@example.com",
    "company_name": "Client LLC",
    "notes": "",
    "status": "entity_created",
    "created_at": "2026-10-01T09:00:00+00:00",
    "entity_created_at": "2026-10-01T09:00:00+00:00",
    "entity_id": "6710c0ffee0000000000abcf",
    "activity": { "sent": 0, "received": 0, "failed": 0 }
  }
}

409: something is already attached. Nothing is stored.

{
  "error": "A company with this TIN is already registered and is linked to a reseller or an application",
  "code": "entity_exists"
}

409: you already requested it.

{
  "error": "You have already requested a client with this TIN"
}

409: another partner or reseller reserved the TIN. Nothing is stored for this request.

{
  "error": "A client with this TIN has already been requested",
  "code": "tin_reserved"
}

400: not a TIN. A 15-digit TRN gets this too.

{
  "error": "invalid_request",
  "details": [
    {
      "type": "value_error",
      "loc": ["tin"],
      "msg": "Value error, TIN must be 10 digits, starting with 1"
    }
  ]
}

A client is onboarded when a company with its TIN is registered on Tax Star. A client.onboarded webhook tells you the moment it happens. It is optional, and the only client event: a request that is still pending sends nothing.

Subscribe. In the Webhooks panel of your app's settings, tick client.onboarded in the list, or call POST /oauth/webhooks. * includes it.

curl -X POST https://api.taxstar.app/einv/oauth/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/taxstar/webhooks",
    "events": ["client.onboarded"]
  }'

{
  "message": "Webhook created. Store the signing_secret now - it is used to verify event signatures and is shown in full only on create and rotate.",
  "webhook": {
    "id": "6710c0ffee0000000000dcba",
    "url": "https://example.com/taxstar/webhooks",
    "events": ["client.onboarded"],
    "is_active": true,
    "signing_secret": "whsec_..."
  }
}

Try it. Send a signed test event to your URL before you rely on it.

curl -X POST https://api.taxstar.app/einv/oauth/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer $ACCESS_TOKEN"

What you receive. The same body for a pending request that onboards later and for a request linked at once. It carries the client's id, TIN, company name, status and timestamps, never its email or the company's id.

{
  "event": "client.onboarded",
  "created_at": "2026-10-03T12:30:05+00:00",
  "data": {
    "client": {
      "id": "6710c0ffee0000000000abcd",
      "tin": "1000000000",
      "company_name": "Client LLC",
      "status": "entity_created",
      "created_at": "2026-10-01T09:00:00+00:00",
      "entity_created_at": "2026-10-03T12:30:00+00:00"
    }
  }
}

Verify and handle it. Every Taxstar webhook is signed the same way; see Webhooks for the header. Match the event to your own record by data.client.id, and make the handler idempotent: a retry can deliver the same event twice.

// Node.js (Express) - receive a client event
import crypto from "crypto";

app.post(
  "/taxstar/webhooks",
  express.raw({ type: "application/json" }), // keep the raw, unparsed body
  (req, res) => {
    const header = req.headers["x-taxstar-signature"] || "";
    const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
    const expected = crypto
      .createHmac("sha256", process.env.TAXSTAR_WEBHOOK_SECRET)
      .update(parts.t + "." + req.body.toString()) // signed string is "{t}.{raw body}"
      .digest("hex");
    const given = Buffer.from(parts.v1 || "");
    const ok =
      given.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(expected), given);
    if (!ok) return res.sendStatus(400);

    const { event, data } = JSON.parse(req.body.toString());
    if (event === "client.onboarded") {
      // data.client.id is your pre-registered client; data.client.tin is its TIN.
      // Events can repeat (a retry after a slow answer), so make this idempotent.
      markClientOnboarded(data.client.id, data.client.tin);
    }
    res.sendStatus(200); // any 2xx acknowledges; answer within 10 seconds
  }
);

When a company is linked to you, whether it registers after your request or was already registered and free, Tax Star emails its owner once. The email names your application, says it was given editor access to manage the company on Tax Star and that it was connected successfully, and asks the owner to contact Tax Star support if they did not allow it. It also states that the company and all its billing will be managed by the partner.

It carries only your application's name and the company's name; the client's email, TIN and your credentials are never in it. Use a clear application name: it is what the owner reads. A company that disputes a link is handled by Tax Star support. Partners and resellers each have their own email.

Every pre-register call, whatever its outcome, is written to your application's activity log with the action partner_pre_register and a result: pending, linked_existing_entity, refused_duplicate, refused_reserved, refused_already_linked or invalid_request. The entry carries ids only (the client request and, for a link or a refusal, the company), never the TIN, the email or the company name. You can see it under Your apps.

Tax Star also keeps an audit trail of each request, step by step: when it was made and through what, whether it was refused and why, when and how a company was linked to it and the rule that allowed it, what access the link gave, and whether the owner was emailed. It holds the TIN and ids, never an email address or a name. Support uses it to answer how, when and why a TIN is connected to a partner.

The partner endpoints share the rate limits of the rest of the OAuth API, counted per app, and the same token lifetimes. A suspended account cannot pre-register a client; reading and webhooks management of existing ones still work.

The counts are the ones the Tax Star admin panel shows for that company: documents that reached the Peppol network (sent, received) and send attempts whose latest status is a failure (failed). A linked client also includes its entity_id; no other entity data is exposed in the client list. The company's own invoices and data are available through your application once you are its editor. totals on the list covers every client you have pre-registered, not only the current page.

{
  "id": "6710c0ffee0000000000abcd",
  "tin": "1000000000",
  "email": "client@example.com",
  "company_name": "Client LLC",
  "notes": "",
  "status": "entity_created",
  "created_at": "2026-10-01T09:00:00+00:00",
  "entity_created_at": "2026-10-03T12:30:00+00:00",
  "entity_id": "6710c0ffee0000000000abcf",
  "activity": { "sent": 42, "received": 17, "failed": 2 }
}

A partner is an ordinary OAuth app, so there is one event to know about and no separate endpoints: client.onboarded is in the normal webhook event list. The full walkthrough, with the delivery diagram, the signature check and a receiver, is above; creating, testing and rotating a webhook is on Webhooks.

The endpoints are on Partner clients. The same flow for resellers is on Reseller accounts. Roles and what an app may reach are on Roles and permissions. Tokens are on Authentication.