API

How to let other software read your FSMCore data: switch the API on, create a token for each program, choose what it may read, revoke it, and see the calls that were made.

What it is for

The API is a way for another program (your accounts package, a spreadsheet, a report tool) to read your company's data from FSMCore without a person signing in. The page says it like this: "Read-only access to your data for other software, with tokens you create here. Only owners and admins see this page."

Open Settings, then API.

A token is a long secret text. The program sends it with every call, and FSMCore knows from the token which company is asking and what it may read. A token belongs to the company, not to a person: it keeps working when the person who created it leaves.

The API only reads. Nothing can be created, changed or deleted through it.

You will usually hand this page to the person who sets up the other program. The parts they need are What the API can do, Lists, Errors and API documentation.

Who can use it

The rule is checked again when something is saved. Anyone else is refused with Only an owner or admin can create or revoke API tokens. or Only an owner or admin can switch the API on or off.

The API also needs a plan that includes it. See Plans.

Plans

The API is part of the Company, Large and Business plans. During the free trial you have every feature, so the API is there too. See The plans.

On a plan without the API:

• The page shows The API is not part of your plan. Choose a plan with the API in Settings > Billing.
• The Switch API on button and the Create token button are not shown.
• Creating a token is refused with the same sentence.
• Every call answers 403 with the same sentence, also for tokens made earlier.
• The API documentation at /api/docs answers 403.

Your tokens are kept. They work again when you move to a plan with the API. You can still revoke a token, and you can still switch the API off if it was on.

A locked company has no API either. See Errors.

API access

The first section of the page, API access, shows where things stand.

Below that is one line with three things:

• Address: the address the other program calls. It is your company's own address followed by /api/v1, for example https://your-company.fsmcore.com/api/v1. A token works only on this address: a call to fsmcore.com/api/v1 without your company's name in front is refused (403).
• 60 calls a minute per token: the call limit.
• API documentation: a link that opens the API documentation in a new tab.

Switch the API on or off

The API is off until an owner or admin switches it on. The switch is on this page only. It is not in the Features section of the company settings.

To switch it on:

1. Open Settings, then API.
2. Press Switch API on.
3. The window asks Switch the API on? and says "Tokens you create can then read the data you allow them. Nothing can be changed through the API."
4. Press Switch on. The message API switched on shows.

To switch it off:

1. Press the red Switch API off button.
2. The window asks Switch the API off? and says "Every call is refused (403) until you switch it on again. Tokens are kept."
3. Press Switch off. The message API switched off shows.

Switching off is the fast way to stop every program at once. No token is lost: switch it on again and they all work as before.

If the plan does not include the API, the switch-on is refused with API not switched on and the plan sentence.

Create a token

Create one token for each program. Then you can stop one program without touching the others, and the Recent calls list shows which program made each call.

1. Open Settings, then API.
2. Press Create token above the Tokens list. The window Create an API token opens. It says "The token is shown once, right after you create it. Store it somewhere safe."
3. Fill in Name. Required, up to 100 characters. Write what uses it, for example "Accounts sync".
4. Under May read, tick what this token may read. At least one tick is required. See What a token may read.
5. Fill in Expires on if the token should stop by itself. The earliest date is tomorrow. Leave it empty for a token that does not expire. A token with a date stops working at the end of that day, on your company's clock.
6. Press Create token. The message Token created shows.
7. Copy the token straight away. See Copy the new token.

You can create tokens while the API is off. They start working when you switch it on.

The window does not save while something is wrong. The field with the problem is marked and shows one of these sentences under it:

The same rules are checked again when the token is saved, with the same sentences.

A token cannot be changed after it is made. To change the name, what it may read or the expiry date, create a new token and revoke the old one.

What a token may read

May read is a tick list in two columns. The links Select all and Deselect all above the list tick or untick everything at once.

Give each token only what its program needs. A call for something that was not ticked answers 403.

Some figures also depend on your company's switches:

• Construction tax (RCT) figures are sent only while RCT is switched on for your company.
• Job margin figures are sent only while job margins are switched on for your company and the token has Job margins (with Jobs).

Copy the new token

Right after you create a token, a section New token: with the token's name shows above the list. It says "Copy it now. It is shown only this once; if it is lost, revoke it and create a new one."

1. Press Copy. The button changes to Copied.
2. Paste the token into the other program, or into the place where you keep passwords.
3. Press I have stored it. The section closes.

FSMCore does not keep the token in a readable form, so nobody can show it to you again, not even us. If you close the section or leave the page before copying it, revoke that token and create a new one.

Treat a token like a password. Anyone who has it can read what it was given until it is revoked.

Tokens

The Tokens list shows every token of your company, the newest first. Its description says "Each token reads only what it was given. Revoking one stops it at once." You can show 10, 25 or 50 per page.

An empty list shows No tokens yet and "Create a token for each program that should read your data."

The token itself is never shown in the list.

Revoke a token

Revoke a token when the program is no longer used, when the token was lost, or when it may have been seen by someone who should not have it.

1. Find the token in the Tokens list.
2. Press the red Revoke on its row. It shows on every token that is not revoked yet, expired ones included.
3. The window asks Revoke "Accounts sync"? (with your token's name) and says "Anything using this token stops working at once. This cannot be undone."
4. Press Revoke. The message Token revoked shows.

The token stays in the list with the status Revoked, with who revoked it and when. Its calls stay in Recent calls. A revoked token cannot be switched back on and cannot be deleted from the list. Create a new one if the program is needed again.

Recent calls

The last section, Recent calls, shows "The last 50 calls made with your tokens. Calls are kept 30 days." The newest call is first.

With no calls the section says No calls in the last 30 days.

Every call made with a token of yours is listed, also the refused ones (403, 404) and the ones over the call limit (429). A call with a token that is revoked or has expired is listed with its 401, so you can see a program that still uses an old token. A call with no token, or with a text that is not one of your tokens, is not listed: FSMCore cannot tell whose it is.

A refused call with a revoked or expired token does not change Last used in the Tokens list.

Use the list to check that a new program works, and to see which program is making refused calls.

How long calls are kept

Calls are kept 30 days. Once a day, at 04:00 Irish time, calls older than 30 days are removed. You do not need to clear anything yourself.

What the API can do

The API is read only. Each kind of record can be read in two ways: as a list, and as one record by its id. There is no call that creates, changes or deletes anything.

Every address starts with your company's address and /api/v1.

The token is sent with every call as Authorization: Bearer <token>. The token decides the company. A call can never name another company, and an id of another company's record answers 404.

Deleted records are not returned. Archived clients, sites, jobs and price list items are returned, each with the moment it was archived.

How values are written

• Money is written as text with two decimals, for example "1234.50", with the currency beside it. A document keeps the currency it was issued in.
• A moment (created, changed, voided, approved) is written as date and time with your company's time zone, for example 2026-10-02T14:30:00+01:00.
• A plain date (issue date, due date, valid until, working days) is written as year, month, day: 2026-10-02.
• A paid date is written like a moment, with the date and time as they were typed, on your company's clock.

Clients

A client carries its name and business name, email, phone, address, website, VAT number, tax reference, registration number, default due days, notes and its status.

The status is worked out by FSMCore, the same as in the Clients list: lead, active or archived. The list can be narrowed to one of them with status.

Sites

A site carries its client, name and address. The RCT site number is sent only while RCT is switched on for your company.

Jobs

A job carries its client, site, title, status, quoted value with the currency, the ticked working days with the first and last day, the schedule note and the office notes.

With Job margins (with Jobs) ticked and job margins switched on, each job also carries its margin: invoiced before tax, cash received, crew invoice cost, crew invoice cost still waiting for approval, labour cost and hours, other job costs, total costs, the margin, its percentage and its band, and whether the margin is incomplete. The RCT deducted figure is in it only while RCT is on.

Estimates and invoices

An estimate or invoice carries its number, status, client, job, currency, dates, the client details it was issued to, its texts, the subtotal, tax total and total, and every line.

An invoice also carries its kind, its category, the estimate it came from, the site address, its terms, its reverse charge statement, the paid date, and a payment summary: amount paid, balance due, whether it is settled, and the number of payments. RCT deducted is in the summary only while RCT is on.

Drafts and void documents are included, each with its status.

Crew invoices

A crew invoice carries its number, status, category, who it is from (name only), job, currency, dates, the rejection reason, the office notes, totals, amount paid and its lines.

Draft crew invoices are never returned: a draft belongs to the person writing it. The person's own bank, tax and address details are not sent.

Payments

A payment carries its invoice, currency, amount, the date paid, method, reference and notes. The RCT deducted, RCT rate and RCT authorisation are sent only while RCT is on. Removed payments are not returned.

Price list items

A price list item carries its description, unit, unit price with the currency, tax rate, category, supplier and notes. Archived items are included, with the moment they were archived.

Lists

A list is sent in pages.

Each list can also be narrowed:

The exact words for each status are in the API documentation.

A setting with a value that is not allowed (for example per_page of 500, a sort other than the two above, or a status that does not exist) answers 422 and names the setting.

Call limit

Each token may make 60 calls a minute. The limit is counted per token, so two programs with their own tokens do not slow each other down.

A call over the limit answers 429 and says how many seconds to wait before trying again. The program should wait that long and then carry on. Nothing is lost and the token is not blocked.

Errors

A refused call answers with a number and a short sentence. The number also shows in red in Recent calls.

API documentation

The full description of every address, every setting and every field is on its own page. Open it with the API documentation link in the API access section. It opens in a new tab at /api/docs on your company's address, for example https://your-company.fsmcore.com/api/docs.

Only an owner or admin of that company can open it, only while signed in, and only while the plan includes the API. Everyone else gets a 403 page. So to show it to the person setting up the other program, open it yourself and send them the file from Export.

The page is built from the running software, so it always matches what the API really does.

What you see:

• A menu on the left:
  • Overview: a short description of the API.
  • Endpoints, with one entry for each kind of record: Clients, Crew invoices, Estimates, Invoices, Jobs, Payments, Price list, Sites. Open one to see its two calls (the list and one record), the settings each call takes and an example answer.
  • Schemas: the fields of each kind of record.
• An Export button at the top right. It downloads the description of the API as a file (the OpenAPI format) that many programs can load.
• The base address https://your-company.fsmcore.com/api/v1, with your own company's name in it.
• The sign-in method: a Bearer token, which is the token you create in Settings, API.

The same rules apply as everywhere on this page: 60 calls a minute per token, and read only.

The same description is also at /api/docs.json on your company's address, for a program that reads it directly. The same people can open it.

What happens after

• A new token works at once if the API is on.
• A revoked token stops at once. Its next call answers 401, and that call shows in Recent calls.
• An expired token stops at the end of its last day and shows Expired in the list.
• Switching the API off stops every token at once. Switching it on brings them all back.
• Creating a token, revoking a token and switching the API on or off are recorded: who did it and when. The token itself is never written into that record.
• Reading through the API changes nothing in FSMCore and leaves no mark on the records that were read. It only shows in Last used and in Recent calls.
• No email and no notification is sent when a token is created, revoked or used, or when the API is switched on or off.

Common mistakes

I closed the page before copying the token. The token cannot be shown again. Revoke it and create a new one.

There is no Switch API on button and no Create token button. Your plan does not include the API. The page says so in the API access section. See Plans.

Every call answers 403 although the token is right. The API is off, or the plan does not include it, or the call goes to another company's address. The sentence in the answer says which. See Errors.

One kind of record answers 403, the others work. The token was not given that tick under May read. A token cannot be changed: create a new one with the right ticks and revoke the old one.

The jobs have no margin figures. The token needs Job margins (with Jobs) as well as Jobs, and job margins must be switched on for your company.

RCT figures are missing. They are sent only while RCT is switched on for your company.

A draft crew invoice is missing. Draft crew invoices are never returned. It appears once it is submitted.

My calls do not show in Recent calls. The list shows only calls made with one of your company's tokens. A call with no token, a mistyped token, or a revoked or expired token is not listed. Calls older than 30 days are removed.

A colleague gets a 403 page on the API documentation. Only a signed-in owner or admin of the company can open it. Send them the file from Export.

The program stops every minute with 429. It makes more than 60 calls a minute. Let it wait the seconds the answer names, ask for bigger pages with per_page, and use updated_since so it fetches only what changed.

I want the program to change data in FSMCore. The API cannot do that. It is read only.