Company lookup by NIP

The /company/nip-lookup endpoint fetches Polish company data from the GUS registry. Use it to auto-fill client details or the buyer when creating a document, instead of asking the user to retype everything.

Required scope: gus:company:read.

Lookup

curl -s "https://prod.api.fakturnia.pl/external/v1/company/nip-lookup?nip=5252248481" \
  -H "Authorization: Bearer $TOKEN"

Pass the NIP as 10 digits. Dashes and spaces are ignored, so 525-224-84-81 works too.

{
  "success": true,
  "data": {
    "company": {
      "nip": "5252248481",
      "name": "PRZYKLAD SPOLKA Z OGRANICZONA ODPOWIEDZIALNOSCIA",
      "regon": "146061343",
      "street": "ul. Prosta 1 lok. 2",
      "postcode": "00-001",
      "city": "Warszawa",
      "country": "Polska",
      "countryCode": "PL"
    }
  }
}

Errors

Status	Code	Meaning
`400`	`INVALID_NIP`	the NIP is not 10 digits
`404`	`COMPANY_NOT_FOUND`	no company with this NIP in the GUS registry

Typical flow

The user enters a NIP in your form.
You call nip-lookup and pre-fill the form with the returned data.
On confirmation you create a client or pass the buyer details directly in POST /documents.

The data comes from a public registry and is a convenience: let the user correct it before issuing an invoice. Also remember that sending to KSeF requires the buyer's full address.

Documentation

Get started

Quickstart: Issue your first invoice in five minutes.

Authentication: OAuth 2.0 client credentials, tokens and scopes.

Invoicing

Document types & amounts: Every document type and exactly how amounts are computed, to the grosz.

Creating documents: The complete field-by-field guide to POST /documents: parties, line items, payment, annotations.

Sending to KSeF: Issue an invoice, send it to KSeF and wait for the result correctly.

Correcting documents: Issue corrections via the API: regular, advance and settlement corrections, with the delta and proportional tax rules.

KSeF connection: Configure, test and remove the KSeF certificate connection through the API.

Order references: Link documents to orders in your system and find unlinked documents.

Resources

Clients: Create, search, update and delete clients (buyers) through the API.

Products: Manage the product and service catalog used on documents.

Settings: Read and update account settings: date format and document numbering.

Warehouse: Warehouses, stock adjustments, stock reports and automatic WZ documents for invoices.

Employees & permissions: Create employee accounts and manage their permissions through the API.

Recurring documents: Read recurring rules, their generation history, and pause or resume them through the API.

Email accounts: Read which mailboxes send documents from the account and whether they are verified. Read-only.

Company lookup (NIP): Fetch Polish company data from the GUS registry by NIP.

Core concepts

History & activity: Read the journal of a document, the account activity feed, an employee feed and the stock movement ledger.

Errors: Status codes, the error envelope and stable error codes.

Dictionaries: Every enum the API returns: document types, VAT rates, currencies, country codes, GTU and more.

Rate limits: Per-endpoint limits, 429 handling and backoff.

PDF rendering queue: Handling 429 WAIT_PDF_QUEUE when downloading invoice PDFs.

Pagination: Paging through list endpoints with currentPage and itemsPerPage.

Idempotency: Safely retry writes with Idempotency-Key.

Webhooks: Events, delivery format and signature verification.

Tools

Tools: Postman collection, curl-based CLI, OpenAPI client generation and the agent skill file.

For agents & bots: Machine-readable endpoints: OpenAPI, llms.txt and Markdown.

MCP server (ChatGPT, Claude, Gemini & more): Connect a Fakturnia account to ChatGPT, Claude, Gemini, Mistral Vibe (Le Chat), Perplexity, GitHub Copilot or Cursor: OAuth 2.1, tools, the guided invoice flow and limits.

Changelog: Versioning policy and release notes.

Company lookup by NIP

Lookup#

Errors#

Typical flow#

Lookup

Errors

Typical flow