Your workflow.
Our API.
The API provides access to the same profiles, files, applications and events as the member portal. Every request is limited by data ownership and the API key scopes.
Create an API key ↗Download the OpenAPI 3.1 JSON specification for Postman, code generators and other tools.
1. Create and store a key
Open Member portal → API access → Create key. Set an integration name, expiry date and the smallest required scope set. The token is shown once. Store it on your server in an environment variable; never put it in public JavaScript.
Authorization: Bearer YOUR_TOKEN
Accept: application/jsonBearer requests do not require CSRF. A browser session must first call GET /api/v1/session and then send X-CSRF-Token with every state-changing request. Cross-origin browser access is disabled by default, so third-party integrations should call the API from their server.
Registration, password recovery requests and the contact form require a one-use CAPTCHA. In the same session call GET /captcha?purpose=register|forgot|contact, render the PNG in data.image, then submit captcha_id and the five displayed characters as captcha_answer. A challenge lasts 10 minutes and one attempt; issuing a newer challenge invalidates the previous one.
2. Make the first request
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://fams.kz/api/v1/profiles{
"data": [{"id": 123, "kind": "athlete", "name": "Athlete name"}],
"meta": {},
"request_id": "request identifier"
}3. Upload a file and attach a passport
JPG, PNG, WebP and PDF files up to 20 MB are accepted. Files are stored outside the public directory. Keep the returned data.id and pass it as file_id or photo_id.
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@passport.pdf" -F "purpose=identity" \
https://fams.kz/api/v1/filescurl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"profile_id":123,"type":"passport","file_id":"FILE_UUID","number":"N1234567","country":"Kazakhstan","issued_at":"2025-01-15","expires_at":"2035-01-15"}' \
https://fams.kz/api/v1/documentsBoth identity and passport satisfy the identity-document requirement. Other types are driver, medical, consent, organization, insurance_policy, naf_permission and foreign_naf_license. Foreign passport numbers may contain letters and an IIN is optional.
Per-document review: review_note is returned for documents in GET /profiles/{id} and GET /applications/{id}. Show it when the status is changes, cancelled, or expired. An administrator sends POST /admin/review with kind: "document", the document id, and approve, changes, or cancel. Returning or cancelling requires a 5–3000 character reason. The decision updates only that document.
Expiry: once expires_at is earlier than the current date, the API persists status: "expired". Linked active FAMS certificate or document applications move to status: "changes", and the reason identifies the expired document and linked applications. The certificate and QR become invalid immediately while the existing payment remains on the application. Attach an approved renewed document with PATCH /applications/{id} and submit again; a ready paid national certificate is approved automatically without a second charge.
Core routes
| Method and path after /api/v1 | Purpose | Scope |
|---|---|---|
| GET /catalog?kind=service | Services and pricing | Public |
| GET /services/prices | Current MRP and exact KZT price of every active service | applications:read |
| GET, POST /profiles | List or create profiles | profiles:read / profiles:write |
| GET /profiles/summary | Compact athlete directory with document, application, certificate and event counters | profiles:read |
| GET /profiles/{id}/portfolio | One athlete portfolio with profile, documents, certificates, applications and event entries | profiles:read, owner only |
| PATCH /profiles/{id} | Update profile details or photo | profiles:write |
| DELETE /profiles/{id} | Delete an owner profile only when neither the profile nor its photograph has ever been approved | profiles:write |
| POST /profiles/{id}/submit | Submit a profile for review | profiles:write |
| GET /profiles/{id}/vehicles | Read legacy vehicle records from old profiles; creation and editing are disabled | profiles:read |
| POST /documents | Attach a document to a profile | profiles:write |
| GET, POST /files | List or upload files | files:read / files:write |
| GET /applications | List your applications | applications:read |
| POST /applications/quote | Calculate the server-side price | applications:write |
| POST /applications | Create an application draft | applications:write |
| POST /applications/{id}/submit | Validate and submit an application | applications:write |
| POST /applications/{id}/pay | Pay from the balance with duplicate-charge protection | wallet:write |
| GET /applications/{id}/certificate | Download an approved and paid document | applications:read |
| PUT /applications/{id}/sharing | Enable or revoke international licence documents via QR | applications:write, owner only |
| GET /applications/{id}/qr | Download the QR code for an approved, paid international licence | applications:read |
| GET /event-registrations | List own competition entries | applications:read |
| GET, PUT /events/{id}/registration-settings | Classes, crew size, vehicle fields, Excel columns and registration opening | events:read / events:write |
| GET /events/{id}/registrations/export | XLSX by class with only the columns selected by the organiser | events:read |
| GET /events/{id}/registration-options | Eligible profiles, licences, classes, per-entry vehicle fields and document requirements | applications:read |
| POST /events/{id}/registrations/batch | Save or submit up to 100 independent pilot entries with per-entry vehicle data | applications:write |
| GET /events/{id}/registrations | List athlete entries, selected vehicles and crews for the organiser | events:read |
| PATCH /events/{id}/registrations/{registration_id} | Approve, return with a reason, or reject | events:write |
| GET /messenger | Allowed conversations only: administration and related competitions | notifications:read |
| GET /messenger/{perspective}/registrations/{id} | Conversation for one competition entry | notifications:read |
| POST /messenger/{perspective}/registrations/{id}/messages | Message the server-resolved allowed recipient | notifications:write |
| GET, POST /events | List events or create a draft | events:read / events:write |
| GET /events/public/{id} | Published event, documentation status and approved standings | Public |
| GET /events/public/{id}/documents/{regulations|results} | Approved regulations or final results; add ?download=1 to download | Public after approval |
| GET /events/public/{id}/documents/additional/{document_id} | Open or download an additional event document | Public for a published event |
| PATCH /events/{id} | Update an event or one of its files | events:write |
| GET, POST /events/{id}/additional-documents | List or add event bulletins, maps, schedules and other documents | events:read / events:write, event owner |
| DELETE /events/{id}/additional-documents/{document_id} | Remove one additional event document | events:write, event owner |
| GET, POST /events/{id}/participants | List participants or add one by certificate | events:read / events:write |
| PATCH, DELETE /events/{id}/participants/{application_id} | Update a standing or remove a participant before submission | events:write |
| GET /contract-templates | Active agreement templates and variables | events:read |
| GET, POST /contracts | List agreements or create and immediately generate a version 3 PDF | events:read / events:write |
| GET /contracts/{id}/{preview|original|pdf} | Unsigned preview, immutable original, or compatibility PDF | events:read, owner or administrator |
| POST /contracts/{id}/request-confirmation | Repeat or recover PDF generation with the FAMS signature and stamp | events:write, event owner |
| POST /contracts/{id}/{replace|cancel} | Create a new version or cancel with a reason | events:write |
| POST /contracts/{id}/scan | Upload the complete organiser-signed PDF for FAMS review | events:write |
| GET /contracts/verify/{token} | Public agreement state, signatory and SHA-256 verification | Public |
| GET /contracts/verify/{token}/pdf | Download the FAMS-confirmed organiser scan | Public after FAMS confirmation |
| GET, PUT /admin/fams-signing | Configure the single FAMS signature and stamp used in new agreements | admin:read / admin:write |
| POST /admin/contracts/{id}/review | Confirm or reject the organiser-signed scan | admin:write |
| GET /wallet | Balance, invoices and transaction history | wallet:read |
| GET /notifications | Notifications | notifications:read |
| GET, POST, DELETE /telegram | View, create a one-time link, or disconnect the Telegram bot | Browser session and CSRF for changes |
| GET /verify/{token} | Public verification without personal data | Public |
| GET /verify/{token}/documents | Holder-approved documents for a valid international licence | Public through an approved QR link |
Applications, insurance and money
GET /services/prices is the authoritative rate list for a signed-in user or integration. It returns the current MRP in mrp.amount_minor, each service multiplier in services[].mrp, the Kazakhstan total in price_kz_minor, and the full CIS total in price_cis_minor where that territory is allowed. Values ending in _minor are integer tiyn. Use these values for display and still accept the amount returned when the application is created as final.
National categories are returned in this order: D, D Junior, D Karting, B Moto, B Junior Moto, E, L, K Moto (Circuit Racing). D Karting is available only to athletes older than 18 who do not have a driving licence document in their profile. The server checks this rule during quoting, creation and submission and returns 422 service_eligibility when it is not met.
Telegram uses the same domain rules as the API. Users link it from the Security page using a single-use 10-minute code; passwords and API keys are never sent to Telegram. The transport webhook is reserved for Telegram and protected by X-Telegram-Bot-Api-Secret-Token. See docs/telegram-bot.md for server setup.
A national certificate always includes its required insurance workflow. Its only payment is the insurance contribution for the chosen category; there is no separate insurance service or switch. The legacy formula remains: category rate × MCI, plus the category CIS surcharge × MCI when that territory is allowed and selected. insurance_coverage_minor is the coverage amount, not the contribution. Do not use response fields to disable insurance.
Only one active application is allowed for the same athlete profile, service/category, selected sport/discipline and year. A repeated POST /applications returns 409 duplicate_application with the existing error.details.application_id; continue that record through PATCH, submit and pay. A national certificate is approved automatically once the athlete profile, photo, every required attached document and payment are all approved or confirmed. The response from the action that completes the last requirement already contains status: "approved", its number and validity dates. National and international certificates always expire on 31 December of the application year; the server sets valid_until and ignores a later client-supplied date.
The server calculates and stores the price. Never submit a client-calculated price. Money fields ending in _minor contain integer tiyn; invoice amount must be a decimal string such as "15000.00". Reuse the same Idempotency-Key and amount when retrying invoice creation after a timeout.
Organiser agreement workflow
New agreements use workflow_version: 3. An administrator configures the FAMS side once through PUT /admin/fams-signing. Upload transparent PNG/WebP signature and stamp images through POST /files with purpose: signature and purpose: stamp. The setting contains the FAMS signatory name, position, private file IDs, image coordinates and scale.
GET /admin/fams-signing returns the single FAMS configuration. Source images have no public URL and only administrators may read them. Each generated PDF stores an immutable snapshot, so later setting changes affect future PDFs only.
- Create an approved organiser profile and event, then call
POST /contracts. The server immediately assigns a number, creates the QR, inserts the FAMS signature and stamp, and stores the immutable PDF. The organiser side remains blank. - Download
GET /contracts/{id}/original, print it, and sign the organiser side by hand. - Upload every signed page as one PDF through
POST /contracts/{id}/scan. The status becomespending. - FAMS calls
POST /admin/contracts/{id}/reviewwithconfirmorreject. Rejection requires a reason.
Only a FAMS-confirmed scan in confirmed state produces valid: true. The public GET /contracts/verify/{token}/pdf returns that confirmed scan. Before confirmation, the QR says the agreement is not yet valid and does not expose the scan. Cancelled and replaced versions retain their archived files but always verify as invalid.
The audit stores global FAMS setting changes, application of the FAMS signature and stamp to each PDF, generation, download, scan upload, review, replacement and cancellation with actor, time, IP and hashes.
FAMS template variables: {{FAMS_SIGNATURE}}, {{FAMS_STAMP}}, {{FAMS_SIGNER_NAME}}, {{FAMS_SIGNER_POSITION}}, {{FAMS_SIGNED_AT}}, {{DOCUMENT_NUMBER}} and {{DOCUMENT_QR}}. Leave the organiser signature and stamp area blank for handwritten completion.
Errors, limits and administrator routes
401 means authentication failed; 403 insufficient scope; 404 missing or foreign-owned record; 409 state, balance or idempotency conflict; 419 CSRF; 422 validation; 429 rate limit; 503 disabled integration. Errors contain error.code, error.message and sometimes error.details. Give support the request_id, never the API key.
List routes accept page and limit from 1 to 100 and return meta.total. Dates use YYYY-MM-DD and Kazakhstan time, UTC+5.
Administrator routes require the administrator role and admin:read / admin:write. GET /admin/athletes lists athlete profiles and supports status, certificate (issued, not_issued, pending) and q filters for name, IIN, phone, city, email or ID. It returns the certificate issue state, latest application, number and validity period together with the account owner and document/application counters. Download the same registry as CSV from GET /admin/export?kind=athletes. Manual balance changes, reversals, permission changes and key management also require a browser session and password confirmation. A bank callback alone never confirms payment; the server verifies the invoice, amount, currency and terminal with the bank.
PUT /admin/profiles/{id}/owner transfers a profile to another active member account. Send current_user_id, target_user_id, a reason of at least five characters and the administrator password. Linked documents, applications, certificates, organiser events, files and competition chat context move atomically. Issued certificate snapshots, paid amounts and ledger entries are preserved. Public QR document access is revoked until the new owner gives consent. Both owners are notified and the action is audited.
National certificates: three lists
GET /admin/national returns national certificates and the current administrator’s separate review, insurance and print lists. Available filters include year, q, service_id, status, paid, insurance, print, page and limit.
POST /api/v1/admin/national/lists/insurance
{"operation":"add","ids":[123,124]}
POST /api/v1/admin/national/lists/insurance/export
{"ids":[123,124]}Other list operations are remove, clear and auto with a year. A list holds up to 200 records. Insurance and printing require approval and payment. Export returns HTTP 201 with data.file.download_url. Insurance produces XLSX; printing produces a ZIP with document.xlsx, foto/ and qr/. An export mark means only that a file was prepared; the site does not send data to third parties or issue a policy.
Certificate verification and QR document consent
GET /verify/{token} returning HTTP 200 means the record exists; only data.valid confirms validity. The base response excludes names, scans and internal notes. An international licence holder enables access with PUT /applications/{id}/sharing and {"enabled":true,"confirmed":true}, and revokes it with {"enabled":false}. An administrator cannot consent for the holder.
GET /verify/{token}/documents opens only while the licence is approved, paid, currently valid and access is enabled. It returns an allowlisted set of fields and approved scan links, without IIN, phone, address, internal UUIDs or storage paths. Every file link rechecks validity and consent, so revocation takes effect immediately.
GET /admin/records/application/{id} returns profile documents attached to the application in entity.documents and every file stored by the application in entity.attachments. For an international event permission, review both collections; the administrator portal displays them in one list with preview and download controls.
An administrator corrects a profile or document metadata with PATCH /admin/records/{profile|document}/{id}, the admin:write scope and the exact updated_at returned by the preceding GET. Review status and the uploaded scan are preserved, the owner is notified, and changed field names are audited. A stale version returns 409. The type of a document attached to an active application is locked, while its other metadata remains editable. Issued certificate snapshots remain unchanged.