Integrations, the open API and webservice access

For some federations, what the secretariat registers during a match is also pushed out live to an external live-graphics, scoreboard and streaming partner: the match set-up when the live report is prepared, the clock starting and pausing, and every goal, card and timeout as it is registered.

This is switched on by Profixio per federation and per sport in configuration, and it runs in the background without showing anything in the interface. It is in use for Swedish basketball, Swedish handball including beach handball, and Norwegian football. Stream links from the partner are read back and attached to the match, using each federation's own branded player domain.

Correcting a match: new events are pushed onwards, but deleting or editing an event afterwards is not. If a mistake has already gone out, ask Profixio support to have it corrected on the receiving side.

For an integration you build yourself, the streaming side has two pieces on the API key:

• A streaming permission, which adds fields to the match endpoints telling you whether a match may be streamed and whether a stream is currently running, and adds each player's privacy reservation to the squad and to the players in the team list so that names and pictures of people who have reserved themselves are not put on screen.
• A callback address, registered on the key, which Profixio calls when the streaming state of a match changes, so a partner does not have to poll.

Both are set up by Profixio when the key is created. How streaming is turned on for a match, and how a player or a team opts out, is covered in Live results, live feeds and streaming.

Swedish basketball exchanges competition data with Genius Sports, the platform behind the federation's public statistics and its broadcast data. This is a federation-level integration operated by Profixio and the federation, not something a club or a tournament administrator switches on.

What moves. Profixio pushes the competition structure, teams, matches, groups and standings to Genius, and reads match results back for matches that have been played but have no result yet. A series has to be mapped to its counterpart at Genius before anything is exchanged; after that it keeps itself in step.

What people see. On a team's page, when the team's competition is synced and the team has been matched to its counterpart, links appear labelled Open Team Statistics and Open Player Statistics, opening the detailed statistics hosted by the provider. Inside the app, the same team gets extra statistics tabs. If those links are missing, the team has not been paired — ask the federation staff who operate the Genius integration.

Who operates it. There is an operator dashboard for federation staff who have the Genius administrator right. The dashboard is where a season's series are mapped, a sync is started or forced, tables and pools are pushed, and syncing is switched off for a series.

Why it is not instant for everything. A change made now is normally pushed within a few minutes, not immediately.

The embedded live-statistics page shown for individual matches is described in Live results, live feeds and streaming.

For Norwegian federations, Profixio talks directly to the Norwegian sports federation's central systems. This runs on a schedule in the background; there is no button to press.

What it covers:

• Signing in with your national sports identity. Users can log in to Profixio with their Norwegian sports ID instead of a separate Profixio password, which also brings across name, birth date and contact details.
• Clubs and districts. Club and district lists are imported from the national register, including club logos where they exist. Norwegian rugby has a club import that runs once a day overnight; Norwegian football has a club and competition feed that runs once a day in the morning.
• Licence checks. Whether a person holds a valid licence can be checked against the national register rather than being registered twice.
• Privacy reservations. People who have registered a reservation against being shown are flagged, and those flags are used to keep them off streams and graphics, and are cleared again outside the window where they are needed.

Because clubs come from the national register, some club and team functions require the club to be linked to its national record. "The club is missing an id in the national register" is a data problem in the register or in the link, not a permissions problem in Profixio — contact Profixio support with the club name.

The equivalent for Swedish federations is a different pipeline with different rules and is described in Swedish member data synchronisation.

API access is not something you can switch on yourself. There is no page in Profixio where you create a key — the API documentation says it plainly: "Contact Profixio to get an API token".

How it works in practice:

1. You contact Profixio and describe what the integration needs to read or write.
2. Profixio creates an application key for you and sets its access level.
3. You send that key with every request. The same key works for both the REST API and the older SOAP webservice.

Because every extra permission is granted explicitly, the usual cause of "the API returns nothing / says I am not allowed" is that the key is correct but that particular permission was never added. Ask Profixio to extend the key rather than trying a different endpoint.

When you ask for a key, it saves a round trip to say: which organisation and sport, which tournaments or seasons, read-only or also writing results, whether you need invoices or payments, whether the integration is for a test system or production, and who the technical contact is.

What a key is tied to. One key belongs to one organisation — a federation, or a district within it. A key issued to one federation cannot read another federation's data, and asking for a tournament that belongs elsewhere returns an error rather than an empty list. Within that organisation, access is narrowed further:

• District-level keys can be limited to a single district, which is used for district-level invoice access.
• Tournament access is set per key: no tournament access at all, read-only, read and write, or read and write across every tournament in the organisation. Individual tournaments can also be granted one by one, each as read or as read-and-write.
• Extra permissions are granted separately and are off by default: invoices, payments, the full player list for an organisation, personal identity numbers, referee export for divisions where referees are not shown publicly, and streaming data.

The full, generated reference for the REST API lives at profixio.com/app/docs. It is open — your developers do not need a Profixio login to read it, only a key to actually call the API.

The page contains:

• every endpoint, with parameters, example requests and example responses,
• a changelog at the top listing what was added or changed and when, going back several years,
• a section mapping old SOAP operations to their REST replacements, for integrations that are migrating,
• a downloadable Postman collection and an OpenAPI specification, at the same address with .postman and .openapi on the end.

A few conventions that apply everywhere and are easy to miss:

• Authentication is a header, X-Api-Secret, containing your application key. There is no username and password and no login call.
• Most lists are paginated. page and limit are optional query parameters; the default page size is 15 and the maximum is 500. Responses carry meta and links blocks with the paging state.
• There is no version number in the address. The API is extended additively — new fields appear, existing ones are not removed without warning — so write clients that ignore fields they do not recognise.

The "try it out" buttons in the documentation run against the documented example data, not against your organisation's live records.

The REST API is organised around three things: an organisation (a federation or district), a season, and a tournament (which in Profixio is also how a series is stored). Everything else hangs off one of those.

Two things worth knowing before you design against it:

• Squads open shortly before the scheduled start of a match and not earlier. How long before is decided per federation — one hour is the normal setting, and Swedish handball uses 45 minutes. Each match carries the time from which its squad becomes available, so read that rather than assuming a fixed number.
• Personal identity numbers are not included in the player lists unless that specific permission has been added to the key for that organisation. The referee export includes the referees' identity numbers.

Each application key may make 120 requests per minute. Requests beyond that are answered with 429 Too Many Requests instead of data.

Every response tells you where you stand:

• X-RateLimit-Limit — the ceiling for the current minute,
• X-RateLimit-Remaining — what is left of it,
• Retry-After — how many seconds to wait, sent with a 429.

Read those headers rather than hard-coding 120: the limit can be adjusted.

Practical advice for staying well inside it:

• Poll the season or tournament match list on a sensible interval instead of asking for matches one at a time. One list request with a large limit costs the same as one request for a single match.
• During live play, poll the tournament's match list rather than looping over every match.
• Payments and invoices support a change cursor, so a sync can ask for "everything after the last one I saw" instead of re-reading the whole history.
• Cache the things that rarely change — clubs, venues, classes, the season tree.

If a legitimate integration genuinely cannot fit inside the limit, talk to Profixio before building retries that hammer the API; sustained 429s from one key are visible and will be followed up.

Before the REST API there was a SOAP webservice, and it is still running. Existing integrations continue to work; there is no shutdown date announced in the product.

It is, however, deprecated. Its own front page carries the notice that the API is deprecated and points to the REST documentation, and the REST documentation keeps a list of which SOAP operation each new endpoint replaces.

What it offers, grouped roughly as the service itself groups it:

• Tournament services — searching for tournaments, tournament details, classes, teams, registrations, clubs, referees, match details, upcoming and played matches, tables, and registering a match result.
• Association services — clubs, players, regions and referees for a federation, seasons, competitions for a club, team contacts for a season, club licence keys.
• Group activity / group training — activities, sessions, activity types and an activity calendar for a federation.

Access. The same application key that Profixio issues for the REST API is used here; you do not need a second one. The service describes three levels: read-only with the application key alone, read-and-write which additionally requires a user name and password, and a tournament-owner level which requires the tournament's own key. Profixio sets the level when the key is created.

If you are building something new, use the REST API instead. It is faster, better documented, has a published changelog, and is where new fields are added. If you maintain an old SOAP integration, the migration list in the REST documentation is the shortest path across.

Matches can be subscribed to as an ordinary calendar feed, which is often all a club or a referee actually needs — no key, no development work.

Three feeds exist: a team's matches, your own matches across teams, and a referee's own appointments. You get the address from the button Add this to your Google Calendar, Outlook or iCal on the relevant page, which offers Google Calendar, Apple Calendar and Microsoft Outlook plus copy-to-clipboard.

The step-by-step instructions for adding a feed to a personal calendar are in Live results, live feeds and streaming.

For anyone wiring a feed into another system rather than into a personal calendar:

• It is a standard iCalendar subscription, not a one-off export. Moves and venue changes are picked up on the consuming system's own refresh schedule, which for Google and Outlook is typically several hours — Profixio does not control it.
• Each entry carries the two team names as the title, start and end time, the tournament and court in the description, a link back to the match page, and map coordinates where the court or venue has them.
• A feed carries matches from roughly a year back plus everything scheduled ahead, capped at 500 entries, and only matches that are visible and have a time set.
• Copy the address only into the calendar or system that should show the matches.
• A referee administrator's version of the referee feed can be limited to the organisations they administer.

Profixio does not connect directly to an accounting package. There is no built-in integration with a named bookkeeping system, and nothing to authorise or install. What exists is two routes out:

1. Pull it through the API. An accounting integration reads invoices and payments through the REST API, with a permission on the key for each:

• Tournament invoices, with their lines and the invoice PDF.
• Completed payments per team, with amount, method, whether it is a refund, note, invoice reference, payment reference and customer, plus the invoice lines behind it. Payments support a cursor so a nightly job can ask only for what is new, and a date filter so an accounting period can be closed off cleanly.
• Club licence invoices for a federation, including updating their status in bulk once they have been reconciled on the accounting side.

Invoice quantities and amounts reflect what was originally ordered, so credit notes exported as separate documents do not subtract the same quantity twice.

2. E-mail the document. For referee expenses, a federation can register an address for its economy system, and a finance reviewer can send an approved referee invoice there as a PDF with the button Send to Economy System. The address is configured under Integration Settings - External Economy System in the referee expense settings, in the field Economy System Email. Profixio records that the invoice has been sent.

Bank files and reconciliation of incoming payments are a separate subject; see Reading bank files and matching payments.

Profixio can expose a single tournament, or a recurring cup across its editions, to an AI assistant so that visitors can ask questions in plain language and get answers from live tournament data. This is a pilot and is set up together with Profixio, not enabled from a settings page.

What the assistant can look up:

• Tournament information — period, classes, fees, whether registration is open and until when, and how many teams are registered.
• Teams, including matching a name or an abbreviation to the right team and linking to its page.
• The match programme, results, stage names and knockout progression, with links to the match pages.
• Published news articles and pages from the tournament's own website.

What it deliberately cannot reach: squads, players and personal data. The endpoints are read-only — the assistant cannot change anything in Profixio.

A recurring cup gets a permanent address that always resolves to the current edition, surviving renames and sponsor changes, with the option of asking about an earlier year. Before the programme is published, the assistant can still answer with the registered teams rather than nothing at all.

Where a federation also uses a separate refereeing and competition system, Profixio is not the only system writing to the underlying database: that system runs alongside it on the same data. That is why a few values in Profixio are marked as owned by the other system and must not be edited, most visibly the internal level numbering on referee roles, which carries an explicit warning never to change it.

What this means in practice:

• A change made in the other system can appear in Profixio without anyone doing anything in Profixio, and the other way round.
• If a value looks wrong and is marked as belonging to the other system, do not correct it in Profixio — raise it with Profixio support, who will find out which system owns it.

Which federations run this way is not something to guess at from a screen; ask Profixio support if you need to know whether it applies to you.

Nothing on this list can be changed by a federation or tournament administrator from a settings page — every one of them is arranged with Profixio.

Work down this list before reporting a fault.

Every call fails with 401. The key is missing, misspelled, sent in the wrong header, or has been deactivated. The header is X-Api-Secret. There is no login call and no bearer token.

Some calls work, one is refused. The endpoint needs a permission the key does not have — invoices, payments, all players, personal identity numbers, referee export and streaming are each granted separately. Ask Profixio to extend the key.

A tournament you expect is missing, or returns an error. The tournament belongs to another organisation, or the key has no access level covering it and no individual grant for it.

The list is empty but the data exists on the website. The matches are hidden individually, or their class is unpublished or closed. Tables also require the class's table and results not to be hidden, and player statistics require statistics to be switched on for the class. See Hiding matches, schedules and results from the public.

Referee names are missing. The division does not show referees publicly. A key can be given the referee-export permission if the federation wants its own systems to receive them.

Squads come back empty. Squads only open shortly before the scheduled start — an hour before in most federations, 45 minutes in Swedish handball. Each match tells you the time from which its squad is available.

Only the first 15 records arrive. That is the default page size. Use limit, up to 500, and follow the paging links.

429 Too Many Requests. You are over 120 requests per minute for that key. Read Retry-After and slow down; fetch lists rather than looping over single records.

A result written through the API does not show. Check the response rather than the screen — a write that fails validation is rejected, not quietly dropped. Writing also requires a key with write access to that specific tournament.