Me and tax codes

The company and key behind a request, the OpenAPI document, and the tax codes for invoices.

Version v1.1, updated 5 October 2026

On this page

Fields
Who am I
OpenAPI document
List tax codes
Related

Three operations that help you set up an integration. GET /v1/me names the company and the key, and GET /v1/tax-codes lists the codes invoice lines take.

Fields

Send says the field is in responses. Receive says a write accepts it; a reference is sent as an object, such as category for category_id. Totals, VAT, numbers and statuses are computed by BIRP and never received.

The company (me)

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
base_currency	string or null	No	No	Yes	ISO 4217 code of the company base currency: the currency of orders and invoices sent without one. Null when the company has none set.
country_code	string or null	No	No	Yes	ISO 3166-1 alpha-2 country of the company. Its tax codes follow the rules of that country. Null when the company has no country set.
id	string (uuid)	Yes	No	Yes	Company identifier.
name	string	Yes	No	Yes	Company name.

The key (me)

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
expires_at	string or null	No	No	Yes	Expiry of the key. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
name	string	Yes	No	Yes	Name given to the key in BIRP.
prefix	string	Yes	No	Yes	Identifier of the key, as the key list in BIRP shows it.
scopes	array of string	Yes	No	Yes	Scopes of the key.

Tax codes

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
code	string	Yes	No	Yes	The value to send as tax_code on invoice lines. Codes follow the rules of the company's country; they are not fixed names.
effective_from	string	Yes	No	Yes	First day the rule applies, YYYY-MM-DD.
effective_to	string or null	No	No	Yes	Day the rule stops applying, YYYY-MM-DD; null while it applies.
label	string	Yes	No	Yes	Legal basis of the code under the rules of the company's country. It is the only description a code has.
rate	string or null	No	No	Yes	Rate in percent, decimal string with four decimals; null for an exempt rule (no VAT).

Who am I

Returns the company and the API key behind the request, with the rate limits that apply.

Scope: none; any valid key.
Idempotency: a read; send it as often as you need.

GET /v1/me

curl "https://api.birp.io/v1/me" \
  -H "Authorization: Bearer $BIRP_API_KEY"

const response = await fetch("https://api.birp.io/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();

<?php
$ch = curl_init("https://api.birp.io/v1/me");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import requests

response = requests.request(
    "GET",
    "https://api.birp.io/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": {
    "company": {
      "base_currency": "MDL",
      "country_code": "MD",
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "Brutaria Exemplu SRL"
    },
    "key": {
      "expires_at": "2027-10-05T00:00:00.000Z",
      "name": "WooCommerce sync",
      "prefix": "EXAMPLE-PREFIX",
      "scopes": [
        "products:read",
        "stock:read",
        "orders:read"
      ]
    },
    "rate_limits": {
      "per_company_per_minute": 1200,
      "per_key_per_minute": 600,
      "window_seconds": 60
    }
  }
}

OpenAPI document

Returns the OpenAPI 3.1 document of this API, the contract these pages are built from.

Scope: none, and no key.
Idempotency: a read; send it as often as you need.

It needs no key and no scope. Generate a client from it, or compare it with the version you built against.

GET /v1/openapi.json

curl "https://api.birp.io/v1/openapi.json"

const response = await fetch("https://api.birp.io/v1/openapi.json", {
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();

<?php
$ch = curl_init("https://api.birp.io/v1/openapi.json");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import requests

response = requests.request(
    "GET",
    "https://api.birp.io/v1/openapi.json",
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "info": {
    "title": "BIRP public API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "servers": [
    {
      "url": "https://api.birp.io"
    }
  ]
}

List tax codes

Lists the tax codes valid at a date under the rules of the company's country, with their rate and validity. Send one as the tax_code of each invoice line.

Scope: invoices:read.
Idempotency: a read; send it as often as you need.

Without date, the current day of the company applies. A code without a rate is an exemption.

GET/v1/tax-codes

Parameters

datestring (date), in query: YYYY-MM-DD. Left out: the company today.Example 2026-10-05

GET /v1/tax-codes

curl "https://api.birp.io/v1/tax-codes" \
  -H "Authorization: Bearer $BIRP_API_KEY"

const response = await fetch("https://api.birp.io/v1/tax-codes", {
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();

<?php
$ch = curl_init("https://api.birp.io/v1/tax-codes");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import requests

response = requests.request(
    "GET",
    "https://api.birp.io/v1/tax-codes",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": [
    {
      "code": "STANDARD",
      "effective_from": "2015-01-01",
      "effective_to": null,
      "label": "Tax code, article on the standard rate",
      "rate": "20.0000"
    },
    {
      "code": "ZERO",
      "effective_from": "2015-01-01",
      "effective_to": null,
      "label": "Tax code, article on zero-rated supplies",
      "rate": "0.0000"
    }
  ],
  "date": "2026-10-05"
}

Errors particular to this operation:

422 tax_rules_unavailable
422 validation_failed

first-request
invoices
rate-limits

Fields

Who am I

OpenAPI document

List tax codes

Related