Eksport i przenoszenie danych

The file

• Name: firma-export-YYYY-MM-DD.json (the day of the export, UTC).
• Format: one JSON document (RFC 8259), UTF-8.
• Interface: GET https://firma.kfbase.com/v1/orgs/{orgId}/export, signed in as the owner; answered with Content-Disposition: attachment. The same file at any time, free of charge. Automated access for a destination provider (for example with a token) may be added later; until then the owner downloads the file and hands it over, and we answer the destination provider’s technical questions about the format.
• Files (photos, videos, voice notes, documents) are listed in files with a url to the original file, valid for 7 days (filesValidUntil). Download a new export for new links.

Conventions

What	How it is written
Ids	UUID strings (RFC 9562, mostly version 7). Fields ending in Id/By refer to the id of another record.
People	userId, createdBy, approvedBy and similar refer to people[].userId.
Moments in time	ISO 8601 in UTC with Z, e.g. 2026-11-01T07:05:00.000Z (fields ending in At, and those marked time)
Calendar days and months	YYYY-MM-DD / YYYY-MM, in the business’s time zone (organization.timezone, an IANA zone name)
Money	Integers in the smallest unit of organization.currency (ISO 4217): grosz for PLN, pence for GBP
Quantities	quantityMilli: the quantity × 1000 (1.5 h = 1500)
Durations	workedMs: milliseconds
Positions	lat/lng: WGS 84 degrees; accuracyM: metres
Empty	null. Records removed in the app stay in the file with deletedAt set (history is kept).

Versioning

format is always "firma-kfbase-export". formatVersion is 2. New sections or fields may be added without changing the version; a field is removed or changes meaning only with a new formatVersion, announced on this page.

• 2 (2026-11-01): no private conversations; conversationMembers and the title, directKey and createdBy fields of conversations removed.
• 1 (2026-11-01): first version.

Sections

format

The text "firma-kfbase-export".

formatVersion

The format version (a number, now 2).

exportedAt

When the file was made (time).

filesValidUntil

Until when the links in files work (time).

organization

The business (one object).

Field	Type	Meaning
id	text	Id of the business
name	text	Name
timezone	text	IANA time zone, e.g. Europe/Warsaw
currency	text	PLN or GBP
billingCountry	text	Billing country (ISO code) for the VAT wording on our invoices; null until chosen
contactEmail	text	How clients reach the business (on quotes)
contactPhone	text	Phone shown on quotes
street	text	Registered address of the business
postalCode	text
city	text
taxId	text	Tax number (NIP, VAT number or company number)
demoExpiresAt	time	Set only for demo companies
closedAt	time	When the owner closed the business
closedBy	id	Who closed it
deleteAfter	time	When a closed business is deleted
locationEnabledAt	time	Location at work on since then; null = off
locationEnabledBy	id	Who turned it on
locationReviewDueAt	time	From then on the office is asked about positions past the retention period
referralCode	text	The business’s own code for recommending Firma@KFBase
firstPaidAt	time	When it first had a paid plan
createdAt	time	When the business was created

people

Everyone who is or was in the business.

Field	Type	Meaning
userId	id	Id of the person
name	text	Name in this business
email	text	Sign-in e-mail (null for a worker added without one, or once anonymised)
role	text	owner, admin or worker
phone	text	Phone
address	text	Address
createdAt	time	Added to the business
removedAt	time	Removed from the business
anonymisedAt	time	Personal details erased (the name is then a label)

clients

Field	Type	Meaning
id	id
type	text	company or person
name	text	Name
nip	text	Tax number (Polish NIP or other VAT id)
street	text	Address
postalCode	text
city	text
email	text
phone	text
notes	text	Office notes
anonymisedAt	time	Personal details erased
status	text	active or archived
createdAt	time
updatedAt	time

clientContacts

Contact persons of a client.

Field	Type	Meaning
id	id
clientId	id	The client
name	text
position	text	Job title
phone	text
email	text
isPrimary	boolean	The main contact
sortOrder	integer	Order in the list
createdAt	time
updatedAt	time

projects

Field	Type	Meaning
id	id
name	text
clientId	id	The client, or null
address	text	Site address
lat	number	Site position
lng	number
notes	text
status	text	planned, active, done or archived
createdAt	time
updatedAt	time
deletedAt	time

projectTeams

Who is on a project’s team.

Field	Type	Meaning
projectId	id
userId	id
createdAt	time	Added
deletedAt	time	Removed (not exported)

projectBilling

How a project is billed.

Field	Type	Meaning
projectId	id
billingType	text	fixed or hourly
priceGrosz	integer	Fixed price (money)
clientHourlyRateGrosz	integer	Hourly rate for the client (money)
updatedAt	time

projectCosts

Field	Type	Meaning
id	id
projectId	id
date	day
category	text	materials, equipment, subcontractor or other
description	text
amountGrosz	integer	Amount (money)
createdBy	id
createdAt	time
updatedAt	time
deletedAt	time

tasks

Field	Type	Meaning
id	id
projectId	id
title	text
description	text
status	text	planned, in_progress, done or cancelled
scheduledStart	time	Planned start
scheduledEnd	time	Planned end
createdBy	id
createdAt	time
updatedAt	time
deletedAt	time

taskAssignments

Who is assigned to a task.

Field	Type	Meaning
taskId	id
userId	id
createdAt	time	Assigned
deletedAt	time	Unassigned

taskLog

The permanent log of every task: work entries from the phones, notes, files and the office’s changes.

Field	Type	Meaning
id	id
taskId	id
userId	id	Who
type	text	Work: started, paused, resumed, finished; note, attachment; office: created, rescheduled, assigned, cancelled, status, edited, hours_corrected
occurredAt	time	When it happened (on the phone)
receivedAt	time	When the server received it
lat	number	Position at the work entry (only if location was on; null after the office deleted positions past the retention period)
lng	number
accuracyM	number	Accuracy of the position
text	text	Text of a note
attachmentId	id	The file (files[].id)
flags	JSON	List of checks, e.g. late_sync, clock_skew_future, task_cancelled
data	JSON	Details of office changes (kind and before/after values; for hours_corrected the corrected session’s start and end)

conversations

The company channel, the projects’ conversations and each worker’s conversation with the office (there are no private conversations; the office can read all of them).

Field	Type	Meaning
id	id
kind	text	company, project or person (a worker and the office)
projectId	id	For project conversations
userId	id	For a worker’s conversation: the worker
createdAt	time

messages

Field	Type	Meaning
id	id
conversationId	id
userId	id	Who wrote it
text	text
attachmentId	id	The file (files[].id)
createdAt	time

files

Photos, videos, voice notes and documents in tasks and conversations.

Field	Type	Meaning
id	id
taskId	id	The task (null for files in conversations)
userId	id	Who added it
kind	text	photo, video, audio or file
fileName	text	Original name (documents)
contentType	text	Media type (RFC 6838), e.g. image/jpeg
sizeBytes	integer
caption	text
status	text	uploaded, or pending (never arrived from the phone)
createdAt	time
url	text	Download link to the original file until filesValidUntil; null if pending

quotes

Field	Type	Meaning
id	id
number	text	e.g. 2026/007 (year and number within the year)
year	integer
seq	integer	Number within the year
status	text	draft, sent, accepted or rejected
title	text
clientId	id
address	text	Site address
validUntil	day
notes	text
projectId	id	The project made from it
sentAt	time
decidedAt	time	Accepted or rejected by the client
decidedName	text	Name the client gave when deciding
decidedBy	id	Office person who recorded a decision given by phone; null when the client decided on the quote’s page
rejectReason	text
createdBy	id
createdAt	time
updatedAt	time
deletedAt	time

quoteLines

Field	Type	Meaning
id	id
quoteId	id
position	integer	Order
kind	text	labour, material or other
description	text
quantityMilli	integer	Quantity × 1000
unit	text	e.g. h, m2, szt.
unitPriceGrosz	integer	Net unit price (money)
vatRate	integer	VAT rate in per cent
createdAt	time
updatedAt	time

invoices

Invoices issued through the business’s invoicing account (Fakturownia or Xero; the invoice documents themselves stay in that service).

Field	Type	Meaning
id	id
projectId	id
provider	text	fakturownia or xero
kind	text	vat, advance or final
externalId	text	Id of the invoice in that service
account	text	The account in that service
number	text	Invoice number
issueDate	day
paymentTo	day	Due date
netGrosz	integer	Net total (money)
grossGrosz	integer	Gross total (money)
paid	boolean
ksefStatus	text	Status in KSeF (Poland’s e-invoicing system)
ksefNumber	text	KSeF number
ksefErrors	JSON	Errors reported by KSeF
createdBy	id
createdAt	time
refreshedAt	time	Last status check in that service

invoicingOrders

Orders sent to the invoicing service (before an invoice is issued).

Field	Type	Meaning
id	id
projectId	id
account	text
externalId	text	Id in that service
netGrosz	integer	Money
grossGrosz	integer	Money
createdBy	id
createdAt	time

invoicingAccount

The connected invoicing account (one object, or null), without its access token.

Field	Type	Meaning
provider	text	fakturownia or xero
account	text	Account name or id
displayName	text	Name shown in the app

hourlyRates

Cost of a person’s hour, from a date.

Field	Type	Meaning
id	id
userId	id
hourlyCostGrosz	integer	Money
validFrom	day
createdBy	id
createdAt	time

absences

Field	Type	Meaning
id	id
userId	id
kind	text	vacation, sick, unpaid or other
fromDate	day
toDate	day	Inclusive
note	text
createdBy	id
createdAt	time
updatedAt	time
deletedAt	time	(removed absences are not exported)
deletedBy	id

hoursApprovals

Months of hours approved by the office.

Field	Type	Meaning
id	id
userId	id
month	month
approvedBy	id
approvedAt	time
workedMs	integer	Hours worked, at approval
absenceDays	integer	Absence days, at approval
reopenedBy	id
reopenedAt	time

subscription

The plan (one object, or null on the free plan).

Field	Type	Meaning
stripeCustomerId	text	Customer id at Stripe (payments)
stripeSubscriptionId	text
status	text	Stripe subscription status, e.g. active, canceled
licences	integer	Paid phone licences
interval	text	month or year
currency	text	PLN or GBP
periodEnd	time	End of the paid period
cancelAtPeriodEnd	boolean
updatedAt	time

workerNotices

The business’s information notice for workers, every published version (shown on the phones).

Field	Type	Meaning
id	id
version	integer	1, 2, … (a new version is acknowledged again)
text	text	The notice (Markdown; Polish, Ukrainian, English parts)
publishedBy	id	Who published it
publishedAt	time

noticeAcknowledgements

Who acknowledged which version on their phone (“I have read it”, not consent).

Field	Type	Meaning
id	id
noticeId	id	The version (workerNotices.id)
userId	id	Who
acknowledgedAt	time

assessments

The business’s own assessments completed in Ustawienia → Dokumenty dla firm, every approved version: the legitimate-interest assessment for location and the data protection impact assessment (DPIA).

Field	Type	Meaning
id	id
kind	text	legitimate-interest or dpia
version	integer	1, 2, … (each approval is a new version)
language	text	The language version of the template: pl, en or uk
answers	JSON	The answers, in the template’s order: [{ "placeholder", "value" }]
text	text	The completed assessment as approved (Markdown)
approvedBy	id	Who approved it
approvedAt	time

locationReviews

The office’s answers to the question about positions older than the retention period (36 months): delete their coordinates, or keep them longer.

Field	Type	Meaning
id	id
userId	id	Who answered
action	text	delete (coordinates cleared) or keep
keepMonths	integer	For keep: for how many months more (12, 24 or 36)
reason	text	For keep: why the positions are still needed
cutoff	time	Positions recorded before this moment were concerned
entries	integer	Number of work entries with such positions
createdAt	time	When the office answered

termsAcceptances

Acceptances of the Terms (with the DPA) and of the location statements.

Field	Type	Meaning
id	id
userId	id	Who accepted
version	text	Version accepted, the Terms version, or location-… for the location statements
acceptedAt	time

problemReports

Problem reports and ideas sent from the apps.

Field	Type	Meaning
id	id
userId	id
kind	text	bug, idea or question
message	text
context	JSON	Technical details sent with it (app version, device, page)
issueUrl	text	Our internal ticket (not accessible to customers)
createdAt	time

Not included

The export is the complete list of the business’s exportable data. Not included, by design:

• Secrets and access: sign-in sessions, phone pairing codes, phones’ push notification tokens, the invoicing service’s access token (Fakturownia API token, Xero tokens) and the secret links of quote and invoice pages. They would let others into the account or the business’s other services; they are useless elsewhere.
• Internal functioning of the Service: sync counters (version), storage keys, background jobs, the link between tasks and calendar events, which messages each person has read and when someone last opened a quote, our security logs and the audit log of support access.
• Other businesses: which business recommended this one (another business’s identifier).

Changes to this page: 2026-11-01 (format versions 1 and 2, see “Versioning”).