{"openapi":"3.1.0","info":{"title":"Flow Affiliate API","version":"1","description":"The App API is called by your backend, signed with an app credential, to report events and run referrals. The Partner API is called by publishers with a Bearer key, to read their links, conversions and earnings. Amounts are integers in minor units (cents) with an ISO 4217 currency code, and the network pays in USD; times are ISO 8601 in UTC."},"servers":[{"url":"https://api.sqaler.io"}],"tags":[{"name":"Keys","description":"Check which app and environment a key belongs to, and whether your setup is ready, before you send anything with it."},{"name":"Events","description":"Report what your users do, server to server. Registrations are attributed to the link or code that brought the user; later events earn commissions and rewards."},{"name":"Attribution","description":"Ask whether a code or click your app caught can be attributed, before the user signs up, and get the attribution key that carries the referral from then on."},{"name":"Affiliates","description":"Your users as affiliates: their own code and results, codes they enter, and how your program is configured."},{"name":"Referral growth","description":"Ladders, boosts and gift links: what a referrer can reach and give away, to show in your referral screen."},{"name":"Account links","description":"Connect one of your users to their Flow Affiliate account, so they can follow what they referred."},{"name":"Share studio","description":"The hosted studio where your users make stories, feed posts, banners and QR codes that carry their own link."},{"name":"Partner account","description":"The partner and the key a request is made with."},{"name":"Links","description":"Tracking links: list them with their results, or create new ones."},{"name":"Conversions","description":"Users attributed to your links, and how far each has come."},{"name":"Earnings","description":"Commissions per conversion, balances and settlements."},{"name":"Reports","description":"Aggregated results, per link or per sub-id."}],"x-tagGroups":[{"name":"App API","tags":["Keys","Events","Attribution","Affiliates","Referral growth","Account links","Share studio"]},{"name":"Partner API","tags":["Partner account","Links","Conversions","Earnings","Reports"]}],"paths":{"/v1/events":{"post":{"operationId":"ingestEvents","tags":["Events"],"summary":"Send events","description":"Reports one event, or a batch of up to 500 as `{ \"events\": [...] }`. Events are stored first and processed right after, so a 202 means received, not yet attributed or paid.\n\nDeduplicated on (`eventId`, environment): sending an event again returns `duplicate` and changes nothing, so retry freely after a timeout or a 5xx.\n\n`user.registered` decides who referred the user. Send it with the `attributionKey` from `POST /v1/attributions` and the new `appUserId`: the key is bound to that user and the referral it stands for wins. Every later event may then carry the key instead of `appUserId`. Sending the `clickId` or `affiliateCode` the user arrived with on `user.registered` still works too.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"events":{"minItems":1,"maxItems":500,"type":"array","items":{"$ref":"#/components/schemas/Event"}}},"required":["events"],"title":"Batch","description":"1 to 500 events, processed in order."},{"$ref":"#/components/schemas/Event"}]}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedEvents"}}}},"400":{"description":"`validation_error`, `renamed_field`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":400,"code":"renamed_field","description":"An event still sends `referralCode`, which is now `affiliateCode`. Nothing is stored; in a batch, `details.events` lists the positions of those events."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/whoami":{"get":{"operationId":"whoami","tags":["Keys"],"summary":"Check a key","description":"Which app and environment the key you signed with belongs to. Nothing is stored, so it is the request to test a connection with: a 401 says whether the key, the secret or the clock is wrong.","security":[{"appSignature":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoAmI"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/verify":{"post":{"operationId":"verifyIntegration","tags":["Keys"],"summary":"Check your setup","description":"Checks, in one signed request, whether your backend is set up right: the key, its environment, your clock, the app and its program, the event types you send and which of them pay publishers, the store links, refused signatures and the last event received. Nothing is stored, so it is safe to call from a \"Test connection\" button with a production key.\n\nSend `{}` for the checks that need nothing from you, and add `events` and `expectedEnvironment` for the rest. A wrong key, secret or clock is still a 401, as on every signed request.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":429,"code":"too_many_attempts","description":"More than 30 checks with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/affiliates/claim":{"post":{"operationId":"claimAffiliate","tags":["Affiliates"],"summary":"Claim an invite code","description":"Binds an invite code to one of your users who already has an account: a code typed in, pasted or carried by a universal link. Before sign-up, ask with `POST /v1/attributions` instead.\n\nSafe to repeat. A registration that arrived earlier without a code is attributed again when the claim arrives. Pass the `clickId` and `platform` you have, so the claim can be tied to the click that led to it.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimAffiliateRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResult"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`code_inactive`, `already_attributed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":404,"code":"not_found","description":"No code like this belongs to your app."},{"status":409,"code":"code_inactive","description":"The code was deactivated or has expired."},{"status":409,"code":"already_attributed","description":"The user is already attributed to another referrer."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/affiliates/app-open":{"post":{"operationId":"recordAppOpen","tags":["Affiliates"],"summary":"Record the first app open","description":"Reports the first open of the app after an install, with the click id or code it came with, so the funnel shows how many clicks became installs. Measurement only: it never attributes or pays. An open with neither a click id nor a code is not counted, and a sandbox key gets the same answer without recording anything.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppOpenRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppOpenResult"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/affiliates/me":{"get":{"operationId":"getAffiliateSummary","tags":["Affiliates"],"summary":"Get a user’s affiliate summary","description":"The user’s own invite code and link, how many people signed up with it, and what they have earned. Creates their referrer account on first use, so call it when the user opens your referral screen.","security":[{"appSignature":[]}],"parameters":[{"name":"appUserId","in":"query","required":true,"description":"Your pseudonymous id for the user. Never an email address or phone number.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"code","in":"query","required":false,"description":"The code the user already shares in your app (3 to 24 letters and digits), kept as theirs here.","schema":{"type":"string","pattern":"^[A-Za-z0-9]{3,24}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AffiliateSummary"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":404,"code":"not_found","description":"Your app has no active friend-referral program."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/affiliates/config":{"get":{"operationId":"getAffiliateConfig","tags":["Affiliates"],"summary":"Get the program’s mode and rules","description":"Which mode your friend-referral program is in for a market, and under which rules, so the app can show the right terms and knows whether to credit referral rewards itself.","security":[{"appSignature":[]}],"parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166 alpha-2 country of the new user. Without it, the program’s default market applies.","schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AffiliateConfig"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/affiliates/codes":{"post":{"operationId":"importAffiliateCodes","tags":["Affiliates"],"summary":"Import your users’ existing codes","description":"Hands over the invite codes your users already share in your own scheme, so each code stays theirs and keeps working here. Safe to repeat. Codes are real identities, so a sandbox key changes nothing and answers `sandbox: true`.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportCodesRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeImportResult"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":404,"code":"not_found","description":"Your app has no active friend-referral program."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/partner-api/me":{"get":{"operationId":"getPartnerAccount","tags":["Partner account"],"summary":"Get the key’s partner","description":"Who the key belongs to, and what it may do. A cheap way to check a key works.","security":[{"partnerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAccount"}}}},"401":{"description":"`invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`partner_suspended`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":401,"code":"invalid_api_key","description":"No key was sent, or the key is unknown, expired or revoked."},{"status":403,"code":"partner_suspended","description":"API access is suspended for this partner account."},{"status":429,"code":"rate_limited","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/partner-api/links":{"get":{"operationId":"listLinks","tags":["Links"],"summary":"List links","description":"Your tracking links, newest first, with all-time clicks, registrations and qualified users.","security":[{"partnerKey":["links:read"]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Items per page.","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"type":"string","maxLength":200}},{"name":"programId","in":"query","required":false,"description":"Only this program.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","inactive"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkPage"}}}},"400":{"description":"`validation_error`, `invalid_cursor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`partner_suspended`, `insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"invalid_api_key","description":"No key was sent, or the key is unknown, expired or revoked."},{"status":403,"code":"partner_suspended","description":"API access is suspended for this partner account."},{"status":429,"code":"rate_limited","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."},{"status":403,"code":"insufficient_scope","description":"The key lacks the scope this endpoint needs."},{"status":400,"code":"invalid_cursor","description":"`cursor` is not one this API handed out."}]},"post":{"operationId":"createLink","tags":["Links"],"summary":"Create a link","description":"A new tracking link in a program you are an active member of. Its code is generated, and doubles as an affiliate code.","security":[{"partnerKey":["links:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedLink"}}}},"400":{"description":"`validation_error`, `destination_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`partner_suspended`, `insufficient_scope`, `membership_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"invalid_api_key","description":"No key was sent, or the key is unknown, expired or revoked."},{"status":403,"code":"partner_suspended","description":"API access is suspended for this partner account."},{"status":429,"code":"rate_limited","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."},{"status":403,"code":"insufficient_scope","description":"The key lacks the scope this endpoint needs."},{"status":400,"code":"destination_not_allowed","description":"`destinationUrl` is not on the app’s own domain."},{"status":403,"code":"membership_required","description":"You are not an active member of the program."},{"status":404,"code":"not_found","description":"`campaignId` is not an active campaign of the program."}]}},"/v1/partner-api/links/{id}":{"get":{"operationId":"getLink","tags":["Links"],"summary":"Get a link","security":[{"partnerKey":["links:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The link’s `id`.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`partner_suspended`, `insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"invalid_api_key","description":"No key was sent, or the key is unknown, expired or revoked."},{"status":403,"code":"partner_suspended","description":"API access is suspended for this partner account."},{"status":429,"code":"rate_limited","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."},{"status":403,"code":"insufficient_scope","description":"The key lacks the scope this endpoint needs."},{"status":404,"code":"not_found","description":"You have no link with this id."}]}},"/v1/partner-api/conversions":{"get":{"operationId":"listConversions","tags":["Conversions"],"summary":"List conversions","description":"Users attributed to your links, newest first, in the key’s environment.","security":[{"partnerKey":["conversions:read"]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Items per page.","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"type":"string","maxLength":200}},{"name":"from","in":"query","required":false,"description":"Start, inclusive: a date (`2026-11-01`) or an ISO 8601 time.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End, inclusive: a date counts to the end of that day (UTC), or an ISO 8601 time.","schema":{"type":"string","format":"date"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["qualification_pending","qualified","rejected","reversed"]}},{"name":"programId","in":"query","required":false,"description":"Only this program.","schema":{"type":"string","format":"uuid"}},{"name":"linkId","in":"query","required":false,"description":"Only this link.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionPage"}}}},"400":{"description":"`validation_error`, `invalid_cursor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`partner_suspended`, `insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"invalid_api_key","description":"No key was sent, or the key is unknown, expired or revoked."},{"status":403,"code":"partner_suspended","description":"API access is suspended for this partner account."},{"status":429,"code":"rate_limited","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."},{"status":403,"code":"insufficient_scope","description":"The key lacks the scope this endpoint needs."},{"status":400,"code":"invalid_cursor","description":"`cursor` is not one this API handed out."}]}},"/v1/partner-api/commissions":{"get":{"operationId":"listCommissions","tags":["Earnings"],"summary":"List commissions","description":"What you have earned, one row per commission, newest first.","security":[{"partnerKey":["reports:read"]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Items per page.","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"`nextCursor` from the previous page.","schema":{"type":"string","maxLength":200}},{"name":"from","in":"query","required":false,"description":"Start, inclusive: a date (`2026-11-01`) or an ISO 8601 time.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End, inclusive: a date counts to the end of that day (UTC), or an ISO 8601 time.","schema":{"type":"string","format":"date"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending_review","approved","in_settlement","paid","rejected","reversed","disputed"]}},{"name":"programId","in":"query","required":false,"description":"Only this program.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionPage"}}}},"400":{"description":"`validation_error`, `invalid_cursor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`partner_suspended`, `insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"invalid_api_key","description":"No key was sent, or the key is unknown, expired or revoked."},{"status":403,"code":"partner_suspended","description":"API access is suspended for this partner account."},{"status":429,"code":"rate_limited","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."},{"status":403,"code":"insufficient_scope","description":"The key lacks the scope this endpoint needs."},{"status":400,"code":"invalid_cursor","description":"`cursor` is not one this API handed out."}]}},"/v1/partner-api/payouts/summary":{"get":{"operationId":"getPayoutSummary","tags":["Earnings"],"summary":"Get balances and settlements","description":"Your balances per currency, from pending to paid, and your ten latest settlements.","security":[{"partnerKey":["reports:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutSummary"}}}},"401":{"description":"`invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`partner_suspended`, `insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":401,"code":"invalid_api_key","description":"No key was sent, or the key is unknown, expired or revoked."},{"status":403,"code":"partner_suspended","description":"API access is suspended for this partner account."},{"status":429,"code":"rate_limited","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."},{"status":403,"code":"insufficient_scope","description":"The key lacks the scope this endpoint needs."}]}},"/v1/partner-api/reports/links":{"get":{"operationId":"getLinkReport","tags":["Reports"],"summary":"Get the link report","description":"Clicks, registrations, qualified users and commissions per link, or per link and sub-id, over a period. The last 30 days when no period is given.","security":[{"partnerKey":["reports:read"]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Start, inclusive: a date (`2026-11-01`) or an ISO 8601 time.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End, inclusive: a date counts to the end of that day (UTC), or an ISO 8601 time.","schema":{"type":"string","format":"date"}},{"name":"groupBy","in":"query","required":false,"description":"`subid`: one row per link and sub-id combination.","schema":{"default":"link","type":"string","enum":["link","subid"]}},{"name":"programId","in":"query","required":false,"description":"Only this program.","schema":{"type":"string","format":"uuid"}},{"name":"linkId","in":"query","required":false,"description":"Only this link.","schema":{"type":"string","format":"uuid"}},{"name":"currency","in":"query","required":false,"description":"Commission currency; defaults to the one you earn most in.","schema":{"type":"string","minLength":3,"maxLength":3}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkReport"}}}},"400":{"description":"`validation_error`, `invalid_period`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`partner_suspended`, `insufficient_scope`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"invalid_api_key","description":"No key was sent, or the key is unknown, expired or revoked."},{"status":403,"code":"partner_suspended","description":"API access is suspended for this partner account."},{"status":429,"code":"rate_limited","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."},{"status":403,"code":"insufficient_scope","description":"The key lacks the scope this endpoint needs."},{"status":400,"code":"invalid_period","description":"`to` is before `from`."}]}},"/v1/account-links/sessions":{"post":{"operationId":"createAccountLinkSession","tags":["Account links"],"summary":"Start linking an account","description":"A one-time page where your signed-in user connects their account in your app to their Flow Affiliate account. Open the `url` in the system browser, not a WebView: the person signs in there, with BankID by default. It works once, for 15 minutes, and needs a production key.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountLinkSessionRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountLinkSession"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`production_only`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":409,"code":"production_only","description":"Sent with a sandbox key. Account links are real identities."}]}},"/v1/account-links":{"get":{"operationId":"getAccountLink","tags":["Account links"],"summary":"Check whether a user is linked","description":"Whether one of your users has linked their account, so the app can show \"connected\" instead of the button.","security":[{"appSignature":[]}],"parameters":[{"name":"appUserId","in":"query","required":true,"description":"Your pseudonymous id for the user. Never an email address or phone number.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountLinkStatus"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."}]}},"/v1/share/assets":{"get":{"operationId":"listShareAssets","tags":["Share studio"],"summary":"List a user’s share material","description":"The postcards, posters and cards one of your users has made, newest first, each with its own code, results and a signed image link to show in your app.","security":[{"appSignature":[]}],"parameters":[{"name":"appUserId","in":"query","required":true,"description":"Your pseudonymous id for the user. Never an email address or phone number.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareAssetList"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."}]}},"/v1/share/sessions":{"post":{"operationId":"createShareSession","tags":["Share studio"],"summary":"Open the share studio for a user","description":"A link to the hosted studio for one of your users, where they make postcards, posters and QR codes that carry their own link. Open it in a WebView or a browser tab. It works for about half an hour; ask for a new one each time the user opens the studio. Creates their referrer account on first use, and needs a production key.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareSessionRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareSession"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`production_only`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":409,"code":"production_only","description":"Sent with a sandbox key: the studio would hand out real links to test users."},{"status":404,"code":"not_found","description":"Your app has no active friend-referral program."}]}},"/v1/referrals/growth":{"get":{"operationId":"getReferralGrowth","tags":["Referral growth"],"summary":"Get a referrer’s ladders, boosts and gift links","description":"Everything to show on a user’s referral screen beyond their code: progress up each ladder, boosts running now or soon, whether they can send gifts, and the gift links they have made. Creates their referrer account on first use.","security":[{"appSignature":[]}],"parameters":[{"name":"appUserId","in":"query","required":true,"description":"Your pseudonymous id for the user. Never an email address or phone number.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralGrowth"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":404,"code":"not_found","description":"Your app has no active friend-referral program."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/referrals/boosts":{"get":{"operationId":"listActiveBoosts","tags":["Referral growth"],"summary":"List active boosts","description":"Boosts on your friend-referral program that run now or start within a week.","security":[{"appSignature":[]}],"parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166 alpha-2. Only boosts that apply there are returned.","schema":{"type":"string","pattern":"^[A-Z]{2}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralBoostList"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/referrals/gift-links":{"post":{"operationId":"createGiftLink","tags":["Referral growth"],"summary":"Create a gift link","description":"Makes a gift link for one of your users to send to a friend, within the campaign’s limits. The friend gets the gift when they complete a qualifying event.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGiftLinkRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftLink"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`referrer_blocked`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`gifts_unavailable`, `gift_link_limit`, `gift_limit_reached`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`gift_link_daily_limit`, `too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":403,"code":"referrer_blocked","description":"This referrer is suspended or blocked and cannot send gifts."},{"status":404,"code":"not_found","description":"Your app has no active friend-referral program."},{"status":409,"code":"gifts_unavailable","description":"No campaign of the program offers gift links right now."},{"status":409,"code":"gift_link_limit","description":"The referrer already has as many open gift links as the campaign allows."},{"status":409,"code":"gift_limit_reached","description":"The referrer has given away as much as the campaign allows."},{"status":429,"code":"gift_link_daily_limit","description":"The referrer has made as many gift links today as the campaign allows."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/referrals/gift-links/{id}/revoke":{"post":{"operationId":"revokeGiftLink","tags":["Referral growth"],"summary":"Revoke a gift link","description":"Stops a gift link from carrying a gift. Friends who already used it keep theirs, and the link keeps working as the referrer’s own link.","security":[{"appSignature":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The gift link’s `id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeGiftLinkRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokedGiftLink"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":404,"code":"not_found","description":"The user has no gift link with this id, or your app has no active friend-referral program."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/attributions":{"post":{"operationId":"createAttribution","tags":["Attribution"],"summary":"Ask whether a referral can be attributed","description":"Ask as soon as your app has caught something: the link it was opened with (`url`), your deep-link SDK’s referring params as they are (`params`), the Play install referrer, or a typed code. It works before sign-up, so you can show “Invited by …” on the sign-up screen.\n\nA yes carries an `attributionKey`. Keep it, and once you know the user is new, confirm with `user.registered` carrying the key and the new `appUserId`: that binds the key and attributes the user. A user who is not new never gets the key sent; it expires unused, or you can decline it.\n\nSend an `installId` and asking again from the same install answers with the same key. Without one, every yes is a new key, unless `appUserId` names a user who already has one for this code.","security":[{"appSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributionRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributionVerdict"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/attributions/{key}":{"get":{"operationId":"getAttribution","tags":["Attribution"],"summary":"Get an attribution key","description":"What became of a key: who it belongs to, whether it was registered or declined, and the conversion it made.","security":[{"appSignature":[]}],"parameters":[{"name":"key","in":"path","required":true,"description":"The `attributionKey`, `fga_…`.","schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribution"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":404,"code":"not_found","description":"No key like this belongs to your app in this environment."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}},"/v1/attributions/{key}/decline":{"post":{"operationId":"declineAttribution","tags":["Attribution"],"summary":"Decline an attribution key","description":"Optional. When you have decided the user behind a key is not new, you can simply never send the key. Declining it says why: the key is closed at once, and the publisher sees your reason instead of a key that expired without a word.\n\nA declined key is refused on every event (`key_declined`). Declining again changes nothing. A key already registered cannot be declined: undo what it earned with a reversal.","security":[{"appSignature":[]}],"parameters":[{"name":"key","in":"path","required":true,"description":"The `attributionKey`, `fga_…`.","schema":{"type":"string","maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeclineAttributionRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribution"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_signature`, `invalid_timestamp`, `stale_timestamp`, `invalid_key`, `invalid_signature`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`key_registered`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_attempts`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-errors":[{"status":400,"code":"validation_error","description":"The request does not match the schema. `details` says which fields failed and why."},{"status":401,"code":"missing_signature","description":"One of `x-fg-key`, `x-fg-timestamp` and `x-fg-signature` is missing."},{"status":401,"code":"invalid_timestamp","description":"`x-fg-timestamp` is not Unix time in seconds."},{"status":401,"code":"stale_timestamp","description":"`x-fg-timestamp` is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync."},{"status":401,"code":"invalid_key","description":"The key id is unknown or revoked, or the app is archived."},{"status":401,"code":"invalid_signature","description":"The signature does not match. Sign the exact bytes you send."},{"status":404,"code":"not_found","description":"No key like this belongs to your app in this environment."},{"status":409,"code":"key_registered","description":"The key was already registered."},{"status":429,"code":"too_many_attempts","description":"Too many requests with this key in the last minute. Wait `Retry-After` seconds."}]}}},"components":{"schemas":{"AcceptedEvents":{"type":"object","properties":{"accepted":{"type":"array","items":{"type":"object","properties":{"eventId":{"type":"string"},"status":{"type":"string","enum":["accepted","duplicate","rejected"],"description":"`duplicate`: this `eventId` was received before, and nothing was processed twice. `rejected`: its `attributionKey` could not be used (see `reason`); the event was not stored, so the same `eventId` may be sent again once fixed."},"reason":{"description":"Why a `rejected` event was not taken:\n- `unknown_key`: no key like it belongs to your app in this environment.\n- `key_expired`: the key was never registered, and its attribution window has closed.\n- `key_bound_to_other_user`: the key was registered for another `appUserId`.\n- `key_not_registered`: the key is not bound to a user yet. Only `user.registered` with an `appUserId` binds it.\n- `key_declined`: you declined the key.","type":"string","enum":["unknown_key","key_expired","key_bound_to_other_user","key_not_registered","key_declined"]}},"required":["eventId","status"]}}},"required":["accepted"],"description":"One entry per event sent, in the order sent.","examples":[{"accepted":[{"eventId":"registered:u_8F2K","status":"accepted"},{"eventId":"order:o-77120","status":"rejected","reason":"key_not_registered"}]}]},"AccountLinkSession":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Open this for the user."},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","expiresAt"],"examples":[{"url":"https://sqaler.io/connect/3Jx9…","expiresAt":"2026-11-09T09:45:00.000Z"}]},"AccountLinkSessionRequest":{"type":"object","properties":{"appUserId":{"type":"string","minLength":1,"maxLength":200,"description":"Your pseudonymous id for the user. Never an email address or phone number."},"returnUrl":{"type":"string","maxLength":500,"description":"Where the page sends the person when they are done: your https page or an app-scheme URL."}},"required":["appUserId"],"examples":[{"appUserId":"u_8F2K","returnUrl":"nordshop://settings/flow"}]},"AccountLinkStatus":{"type":"object","properties":{"linked":{"type":"boolean"},"linkedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["linked","linkedAt"],"examples":[{"linked":true,"linkedAt":"2026-11-09T09:41:12.000Z"}]},"AffiliateConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["off","shadow","live"],"description":"`off`: Flow Affiliate is not involved, run your own scheme. `shadow`: keep your scheme; Flow Affiliate works out what it would pay, for comparison. `live`: Flow Affiliate decides; credit exactly what the reward webhook says."},"programId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"campaignId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"currency":{"type":["string","null"]},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"triggerEvent":{"type":"string","description":"The event type that earns it, e.g. `purchase.completed`."},"model":{"type":"string","enum":["fixed","percentage"]},"amount":{"description":"Minor units, for fixed rules.","type":["integer","null"]},"percentBps":{"description":"Basis points of the event’s amount, for percentage rules.","type":["integer","null"]},"maxAmount":{"description":"Ceiling on one payout of a percentage rule, minor units.","type":["integer","null"]},"currency":{"type":"string"},"beneficiary":{"type":"string","enum":["partner","referred_user"],"description":"`partner`: whoever referred the user. `referred_user`: the new user themselves."},"recurring":{"type":"boolean","description":"Pays on every matching event, not just the first."},"holdDays":{"type":"integer"},"qualification":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Conditions the event must meet, e.g. `withinDays`."}},"required":["id","name","triggerEvent","model","amount","percentBps","maxAmount","currency","beneficiary","recurring","holdDays","qualification"]},"description":"The rules in force, to show the terms to your users. Empty when `mode` is `off`."},"updatedAt":{"type":"string","format":"date-time"}},"required":["mode","programId","campaignId","currency","rules","updatedAt"],"description":"Your friend-referral program as it applies to new users in one country. Cache it for a minute.","examples":[{"mode":"live","programId":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","campaignId":"5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d","currency":"USD","rules":[{"id":"9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a","name":"Friend makes a first purchase","triggerEvent":"purchase.completed","model":"fixed","amount":200,"percentBps":null,"maxAmount":null,"currency":"USD","beneficiary":"partner","recurring":false,"holdDays":14,"qualification":{"withinDays":30}}],"updatedAt":"2026-11-01T08:00:00.000Z"}]},"AffiliateSummary":{"type":"object","properties":{"code":{"type":"string","description":"The user’s own invite code."},"url":{"type":"string","format":"uri","description":"Their shareable link for the code."},"programId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","inactive"]},"counts":{"type":"object","properties":{"registered":{"type":"integer","description":"Users who signed up with their code or link."},"qualified":{"type":"integer"},"rejected":{"type":"integer","description":"Rejected or reversed."}},"required":["registered","qualified","rejected"]},"earned":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"integer","description":"Everything earned, in minor units."},"pending":{"type":"integer","description":"Not delivered to the user yet."},"delivered":{"type":"integer","description":"Delivered through your reward webhook."}},"required":["currency","amount","pending","delivered"]},"description":"Per currency."}},"required":["code","url","programId","status","counts","earned"],"description":"One of your users as an affiliate.","examples":[{"code":"k7qxa2mp","url":"https://go.sqaler.io/a/k7qxa2mp","programId":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","status":"active","counts":{"registered":3,"qualified":2,"rejected":0},"earned":[{"currency":"USD","amount":400,"pending":200,"delivered":200}]}]},"AppOpenRequest":{"type":"object","properties":{"clickId":{"description":"`fg_click` from the link that opened the app. A value that is not a click id is ignored, never refused.","type":"string","format":"uuid"},"code":{"description":"`fg_ref`, or the code the app opened with, when there is no click id.","type":"string","minLength":1,"maxLength":100},"platform":{"description":"The platform the app runs on. Any other value is ignored.","type":"string","enum":["ios","android"]}},"examples":[{"clickId":"1d4f9c5e-7a8b-4c2d-9e1f-0a1b2c3d4e5f","platform":"android"}]},"AppOpenResult":{"type":"object","properties":{"matched":{"type":"boolean","description":"Whether the open was tied to a click on one of your links."},"match":{"anyOf":[{"type":"string","enum":["click_id","nearest_click"]},{"type":"null"}],"description":"`click_id`: the click id named it. `nearest_click`: the code led to its most recent click on this platform."}},"required":["matched","match"],"examples":[{"matched":true,"match":"click_id"}]},"Attribution":{"type":"object","properties":{"attributionKey":{"type":"string"},"status":{"type":"string","enum":["pending","registered","declined","expired"],"description":"`pending`: waiting for `user.registered`. `registered`: a registration arrived for the key’s user. `declined`: you closed it. `expired`: the window closed before the key was registered."},"partner":{"type":"object","properties":{"displayName":{"type":"string","description":"Who referred the user, as they are shown."}},"required":["displayName"]},"program":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"appUserId":{"description":"The user the key is bound to; null until it is registered.","type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"declineReason":{"anyOf":[{"type":"string","enum":["existing_user","duplicate","suspected_fraud","other"]},{"type":"null"}],"description":"Why you declined it; null unless `status` is `declined`."},"conversion":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["qualification_pending","qualified","rejected","reversed"]}},"required":["status"]},{"type":"null"}],"description":"The conversion this key made, once the registration has been processed. Null when there is none, or the user was attributed to another referral."}},"required":["attributionKey","status","partner","program","appUserId","createdAt","expiresAt","declineReason","conversion"],"examples":[{"attributionKey":"fga_k7qxa2mpw4ht9bvc3rnd8ezj","status":"registered","partner":{"displayName":"Anna Berg"},"program":{"id":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","name":"Invite friends"},"appUserId":"u_8F2K","createdAt":"2026-11-09T09:28:00Z","expiresAt":"2026-12-09T09:28:00Z","declineReason":null,"conversion":{"status":"qualification_pending"}}]},"AttributionRequest":{"type":"object","properties":{"code":{"description":"`fg_ref`, the code in a `/a/<code>` link, or a code the user typed into your own referral field that you want checked against Flow Affiliate. Case and surrounding spaces do not matter.","type":"string","maxLength":100},"clickId":{"type":"string","format":"uuid","description":"`fg_click` from the link, Branch params or the Play install referrer. Used when there is no code, or the code is not one of yours."},"url":{"description":"The link the app was opened with, as it arrived. `fg_ref` and `fg_click` are read from it, and the code of a Flow Affiliate link (`/a/<code>` on its tracking host). Your app’s own referral links are ignored.","type":"string","maxLength":2000},"params":{"description":"The referring params your deep-link SDK hands you (Branch, AppsFlyer, Adjust), forwarded as they are. Only Flow Affiliate’s own data is read: `fg_ref` and `fg_click` from its own keys, and from any value that is a link carrying them or a Flow Affiliate link, such as `~referring_link`. Keys of your own referral scheme, such as `code`, are never read. Branch’s `+match_guaranteed` sets `confidence`. Nothing else in it is kept.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"installId":{"description":"Your own random id for this install. Asking again with the same id answers with the key it already has, instead of making a new one.","type":"string","minLength":1,"maxLength":200},"source":{"default":"other","description":"How the code reached the app. Worked out from what you send when left out: `branch` for Branch params, `link` for a link or click id, `code_entry` for a code alone. `app_clip` for a click handed over by your App Clip, `install_match` for a click that `POST /v1/installs/match` matched the install to (always recorded with `confidence: probable`). Any other value is recorded as `other`, never refused.","type":"string","enum":["link","branch","play_referrer","code_entry","app_clip","install_match","other"]},"platform":{"description":"The platform the app runs on. Any other value is ignored.","type":"string","enum":["ios","android"]},"confidence":{"description":"How sure your link provider is of the match, e.g. `deterministic` for Branch `+match_guaranteed`. Recorded, never decides anything.","type":"string","enum":["deterministic","probable"]},"appUserId":{"description":"Only when the user already has an account: the key is then bound to them at once. Before sign-up, leave it out.","type":"string","minLength":1,"maxLength":200}},"examples":[{"params":{"+clicked_branch_link":true,"+match_guaranteed":false,"fg_ref":"k7qxa2mp","fg_click":"1d4f9c5e-7a8b-4c2d-9e1f-0a1b2c3d4e5f","~referring_link":"https://example.app.link/AbC123"},"installId":"5b1d0c9e-2f4a-4b8c-9d7e-6f5a4b3c2d1e","platform":"ios"},{"code":"k7qxa2mp","source":"code_entry","platform":"android"}]},"AttributionVerdict":{"oneOf":[{"type":"object","properties":{"attributable":{"type":"boolean","const":true},"attributionKey":{"type":"string","description":"Keep it with the install or the sign-up form. Send it on `user.registered` if you decide the user is new."},"status":{"type":"string","enum":["pending","registered","declined","expired"],"description":"`pending`: waiting for `user.registered`. `registered`: a registration arrived for the key’s user. `declined`: you closed it. `expired`: the window closed before the key was registered."},"partner":{"type":"object","properties":{"displayName":{"type":"string","description":"Who referred the user, as they are shown."}},"required":["displayName"]},"program":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"inviteeBonus":{"anyOf":[{"type":"object","properties":{"amount":{"type":"integer","description":"Minor units."},"currency":{"type":"string"},"qualifyingEvents":{"type":"array","items":{"type":"string"},"description":"Event types the user must complete; the bonus follows the first."},"withinDays":{"type":["integer","null"]},"expiresAt":{"type":"string","format":"date-time","description":"The user must register before this to get it."}},"required":["amount","currency","qualifyingEvents","withinDays","expiresAt"]},{"type":"null"}],"description":"The welcome gift the link carries for the invited user. Null when it carries none."},"expiresAt":{"type":"string","format":"date-time","description":"A key not registered by then is no longer accepted: the program’s attribution window."}},"required":["attributable","attributionKey","status","partner","program","inviteeBonus","expiresAt"]},{"type":"object","properties":{"attributable":{"type":"boolean","const":false},"reason":{"type":"string","enum":["no_affiliate","unknown_code","unknown_click","code_inactive","program_closed","already_attributed"],"description":"- `no_affiliate`: nothing you sent names a code or a click, e.g. the params of an install that came from no link.\n- `unknown_code`: no code like this belongs to your app.\n- `unknown_click`: no code was sent, and the click id is not a click on one of your links.\n- `code_inactive`: the code was switched off or has expired, or its referrer can no longer be paid.\n- `program_closed`: the program the code belongs to is not running.\n- `already_attributed`: the `appUserId` you sent is already attributed."}},"required":["attributable","reason"]}],"description":"Whether the referral can be attributed. A no is an answer, not an error: the status is 200 either way.","examples":[{"attributable":true,"attributionKey":"fga_k7qxa2mpw4ht9bvc3rnd8ezj","status":"pending","partner":{"displayName":"Anna Berg"},"program":{"id":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","name":"Invite friends"},"inviteeBonus":null,"expiresAt":"2026-12-09T09:30:00Z"}]},"ClaimAffiliateRequest":{"type":"object","properties":{"appUserId":{"type":"string","minLength":1,"maxLength":200,"description":"Your pseudonymous id for the user. Never an email address or phone number."},"code":{"type":"string","minLength":1,"maxLength":100,"description":"The invite code the user typed, pasted or opened. Case and surrounding spaces do not matter."},"source":{"default":"code_entry","description":"`universal_link` when the code came from the link that opened the app, `code_entry` when the user typed or pasted it.","type":"string","enum":["code_entry","universal_link"]},"clickId":{"description":"`fg_click` from the link that opened the app. A value that is not a click id is ignored, never refused.","type":"string","format":"uuid"},"platform":{"description":"The platform the app runs on. Any other value is ignored.","type":"string","enum":["ios","android"]}},"required":["appUserId","code"],"examples":[{"appUserId":"u_8F2K","code":"k7qxa2mp","source":"code_entry","platform":"ios"}]},"ClaimResult":{"type":"object","properties":{"touchId":{"type":"string","format":"uuid"},"attributed":{"type":"boolean","description":"Whether the user’s registration is now attributed to this code. False until `user.registered` has been sent and processed."},"attributionKey":{"type":"string","description":"The claim’s attribution key, bound to this user. Events may carry it instead of `appUserId`."}},"required":["touchId","attributed","attributionKey"],"examples":[{"touchId":"6b0f2a51-3c4d-4e8f-9a1b-2c3d4e5f6a7b","attributed":true,"attributionKey":"fga_k7qxa2mpw4ht9bvc3rnd8ezj"}]},"CodeImportResult":{"type":"object","properties":{"imported":{"type":"integer"},"existing":{"type":"integer","description":"Already theirs."},"conflicts":{"type":"array","items":{"type":"object","properties":{"appUserId":{"type":"string"},"code":{"type":"string"},"reason":{"type":"string","description":"`code_taken`: another user holds it here. `invalid_code`: not 3 to 24 letters and digits."}},"required":["appUserId","code","reason"]}},"sandbox":{"description":"Sent with a sandbox key: nothing was imported.","type":"boolean","const":true}},"required":["imported","existing","conflicts"],"examples":[{"imported":1,"existing":0,"conflicts":[{"appUserId":"42","code":"k7qxa","reason":"code_taken"}]}]},"Commission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending_review","approved","in_settlement","paid","rejected","reversed","disputed"]},"amount":{"type":"integer","description":"Minor units."},"currency":{"type":"string"},"fx":{"$ref":"#/components/schemas/FxConversion"},"conversionId":{"type":"string","format":"uuid"},"programId":{"type":"string","format":"uuid"},"programName":{"type":"string"},"campaignId":{"type":"string","format":"uuid"},"campaignName":{"type":"string"},"availableAt":{"type":"string","format":"date-time","description":"When the hold ends and it can be approved."},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"settlementId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","amount","currency","fx","conversionId","programId","programName","campaignId","campaignName","availableAt","approvedAt","settlementId","createdAt"]},"CommissionPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Commission"}},"hasMore":{"type":"boolean"},"nextCursor":{"description":"Pass as `cursor` for the next page; null on the last one.","type":["string","null"]}},"required":["items","hasMore","nextCursor"]},"Conversion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["qualification_pending","qualified","rejected","reversed"]},"createdAt":{"type":"string","format":"date-time"},"registeredAt":{"type":"string","format":"date-time"},"qualifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rejectionReason":{"type":["string","null"]},"reasonCode":{"anyOf":[{"type":"string","enum":["self_affiliate","already_user","program_cap","partner_reversal","other"]},{"type":"null"}],"description":"Set on rejected and reversed conversions."},"programId":{"type":"string","format":"uuid"},"programName":{"type":"string"},"campaignId":{"type":"string","format":"uuid"},"campaignName":{"type":"string"},"appName":{"type":"string"},"linkId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"linkCode":{"type":["string","null"]},"subIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"The sub-ids of the link at the time of the click."},"commissionAmount":{"type":"integer","description":"Commission earned on it so far, not counting rejected or reversed."},"commissionCurrency":{"type":["string","null"]}},"required":["id","status","createdAt","registeredAt","qualifiedAt","rejectionReason","reasonCode","programId","programName","campaignId","campaignName","appName","linkId","linkCode","subIds","commissionAmount","commissionCurrency"],"description":"A user attributed to one of your links. The app’s own user id never leaves the platform."},"ConversionPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Conversion"}},"hasMore":{"type":"boolean"},"nextCursor":{"description":"Pass as `cursor` for the next page; null on the last one.","type":["string","null"]}},"required":["items","hasMore","nextCursor"]},"CreatedLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","description":"Also the affiliate code people can type."},"name":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive"]},"programId":{"type":"string","format":"uuid"},"programName":{"type":"string"},"appName":{"type":"string"},"campaignId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"destinationUrl":{"type":["string","null"]},"subIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"utm":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri","description":"The tracking link to share."},"bioNote":{"type":["string","null"]}},"required":["id","code","name","status","programId","programName","appName","campaignId","destinationUrl","subIds","utm","expiresAt","createdAt","url","bioNote"]},"CreateGiftLinkRequest":{"type":"object","properties":{"appUserId":{"type":"string","minLength":1,"maxLength":200,"description":"Your pseudonymous id for the user. Never an email address or phone number."},"note":{"description":"A note for the referrer, e.g. who the gift is for. Never shown to the friend.","type":"string","maxLength":140}},"required":["appUserId"],"examples":[{"appUserId":"u_8F2K","note":"For Sara"}]},"CreateLinkRequest":{"type":"object","properties":{"programId":{"type":"string","format":"uuid","description":"A program you are an active member of."},"campaignId":{"description":"An active campaign of the program; its default campaign when omitted.","type":"string","format":"uuid"},"name":{"description":"Your own name for the link.","type":"string","minLength":1,"maxLength":120},"destinationUrl":{"description":"Where the link sends desktop visitors. Must be on the app’s own domain.","type":"string","maxLength":2000,"format":"uri"},"subIds":{"description":"Up to 10 keys of your own, reported back on conversions, e.g. `{ \"placement\": \"bio\" }`.","type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"type":"string","maxLength":200}},"utm":{"description":"UTM parameters added to the destination, e.g. `{ \"source\": \"newsletter\" }`.","type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"type":"string","maxLength":200}}},"required":["programId"],"examples":[{"programId":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","name":"Newsletter November","subIds":{"placement":"newsletter"}}]},"DeclineAttributionRequest":{"type":"object","properties":{"reason":{"type":"string","enum":["existing_user","duplicate","suspected_fraud","other"],"description":"`existing_user`: they already had an account. `duplicate`: the same person or device signed up before. `suspected_fraud`: you will not accept this sign-up. `other`: anything else."},"note":{"description":"For our records, never shown to the publisher. Nothing that identifies the person.","type":"string","maxLength":500}},"required":["reason"],"examples":[{"reason":"existing_user"}]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable and machine-readable: branch on this, never on `message`."},"message":{"description":"For people: what went wrong, in English.","type":"string"},"details":{"description":"More about the error. For `validation_error`, which fields failed and why."},"requestId":{"description":"Sent with `internal_error`. Quote it when you contact us.","type":"string"}},"required":["code"]}},"required":["error"],"description":"Every error has this shape, whatever the status.","examples":[{"error":{"code":"not_found","message":"affiliate code not found"}}]},"Event":{"type":"object","properties":{"eventId":{"type":"string","minLength":1,"maxLength":200,"description":"Your stable id for this occurrence, e.g. `registered:<user id>` or `order:<order id>`. Sending it again is safe: it is accepted once."},"type":{"type":"string","minLength":1,"maxLength":100,"description":"Dotted event type, e.g. `user.registered`. Commission and reward rules trigger on it."},"version":{"description":"Version of your payload for this type. Defaults to 1.","type":"integer","minimum":1},"occurredAt":{"description":"When it happened in your system, ISO 8601 with `Z` or an offset.","type":"string","format":"date-time"},"appUserId":{"description":"Your pseudonymous id for the user. Never an email address or phone number. Required unless `attributionKey` names a user already.","type":"string","minLength":1,"maxLength":200},"attributionKey":{"description":"The key from `POST /v1/attributions`. On `user.registered`, with `appUserId`, it binds the key to the new user and attributes them to that referral. On any event after that it may stand in for `appUserId`.","anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"clickId":{"type":"string","format":"uuid","description":"`fg_click` from the landing URL, universal link or Play install referrer. A value that is not a click id is ignored, never refused."},"affiliateCode":{"description":"The publisher’s code: `fg_ref` from the same places, or a code the user typed.","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"reversesEventId":{"description":"The `eventId` of the event this one undoes, for refunds and rejections. With `commissionBase` or `amount` (in the original’s currency) it undoes that part of it, as a partial refund.","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"amount":{"description":"The full revenue the event brings in, integer minor units (cents). Percentage rules pay a share of it unless `commissionBase` is sent.","anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"commissionBase":{"description":"What percentage rules pay a share of, when that is not the full `amount`: for example what the user earns on it. Same currency and minor units as `amount`; it may be larger than `amount`, or sent without it.","anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"currency":{"description":"ISO 4217 code in capitals, shared by `amount` and `commissionBase`. Send it whenever either is set.","anyOf":[{"type":"string","pattern":"^[A-Z]{3}$"},{"type":"null"}]},"metadata":{"description":"Free-form facts about the event. Rules can match on them; `country` (ISO alpha-2) on a registration picks the market.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["eventId","type","occurredAt"],"description":"Something a user did in your app.","examples":[{"eventId":"registered:u_8F2K","type":"user.registered","occurredAt":"2026-11-09T09:30:00Z","appUserId":"u_8F2K","attributionKey":"fga_k7qxa2mpw4ht9bvc3rnd8ezj","metadata":{"country":"SE"}}]},"FxConversion":{"anyOf":[{"type":"object","properties":{"amount":{"type":"integer","description":"What the percentage was of, as the app sent it: the event’s commission base, or its amount without one."},"currency":{"type":"string","description":"The event’s currency."},"rateMicros":{"type":"integer","description":"Units of the commission’s currency per unit of the event’s × 1 000 000."},"rateDate":{"type":"string","format":"date","description":"The ECB reference rate’s date: the latest published on or before the day of the event."},"converted":{"type":"integer","description":"That amount in the commission’s currency; the percentage is of this."}},"required":["amount","currency","rateMicros","rateDate","converted"]},{"type":"null"}],"description":"Set when the event was in another currency: how what the percentage is of was converted before the percentage and any cap applied."},"GiftLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"url":{"type":"string","format":"uri","description":"Share this. It keeps working as the referrer’s link after the gift has run out."},"campaignId":{"type":"string","format":"uuid"},"amount":{"type":"integer","description":"Minor units."},"currency":{"type":"string"},"funding":{"type":"string","enum":["campaign","referrer"]},"maxUses":{"type":"integer"},"uses":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","used_up","expired","revoked"]},"note":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"terms":{"$ref":"#/components/schemas/GiftTerms"}},"required":["id","code","url","campaignId","amount","currency","funding","maxUses","uses","expiresAt","status","note","createdAt","terms"],"description":"A link a referrer sends to one or a few friends, carrying a welcome gift.","examples":[{"id":"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e","code":"gq4m8z2r","url":"https://go.sqaler.io/a/gq4m8z2r","campaignId":"5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d","amount":100,"currency":"USD","funding":"referrer","maxUses":1,"uses":0,"expiresAt":"2026-11-23T09:30:00.000Z","status":"active","note":"For Sara","createdAt":"2026-11-09T09:30:00.000Z","terms":{"friendGets":{"amount":100,"currency":"USD"},"fundedBy":"referrer","qualifyingEvents":["purchase.completed"],"withinDays":30,"referrerGets":[{"ruleName":"Friend makes a first purchase","triggerEvent":"purchase.completed","model":"fixed","amount":100,"percentBps":null,"currency":"USD","reducedBy":100}],"expiresAt":"2026-11-23T09:30:00.000Z","maxUses":1}}]},"GiftTerms":{"type":"object","properties":{"friendGets":{"type":"object","properties":{"amount":{"type":"integer","description":"Minor units."},"currency":{"type":"string"}},"required":["amount","currency"]},"fundedBy":{"type":"string","enum":["campaign","referrer"],"description":"`referrer`: the gift is taken out of the referrer’s own reward for this friend."},"qualifyingEvents":{"type":"array","items":{"type":"string"},"description":"Event types the friend must complete; the gift follows the first."},"withinDays":{"type":["integer","null"]},"referrerGets":{"type":"array","items":{"type":"object","properties":{"ruleName":{"type":"string"},"triggerEvent":{"type":"string"},"model":{"type":"string","enum":["fixed","percentage"]},"amount":{"anyOf":[{"type":"integer","description":"Minor units."},{"type":"null"}]},"percentBps":{"type":["integer","null"]},"currency":{"type":"string"},"reducedBy":{"type":"integer","description":"The part of the referrer’s reward that becomes the friend’s gift."}},"required":["ruleName","triggerEvent","model","amount","percentBps","currency","reducedBy"]},"description":"What the referrer gets for the same friend, after any part given away as the gift."},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"maxUses":{"type":["integer","null"]}},"required":["friendGets","fundedBy","qualifyingEvents","withinDays","referrerGets","expiresAt","maxUses"],"description":"Show these to both people whenever a gift is offered."},"ImportCodesRequest":{"type":"object","properties":{"codes":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"appUserId":{"type":"string","minLength":1,"maxLength":200,"description":"Your pseudonymous id for the user. Never an email address or phone number."},"code":{"type":"string","minLength":1,"maxLength":100,"description":"The code the user shares in your app today."}},"required":["appUserId","code"]}}},"required":["codes"],"examples":[{"codes":[{"appUserId":"41","code":"K7QXA"}]}]},"LadderProgress":{"type":"object","properties":{"ladderId":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"campaignName":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"period":{"type":"string","enum":["campaign","month","quarter","year"],"description":"The window referrals are counted in. Calendar periods are UTC."},"periodKey":{"type":"string"},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"qualified":{"type":"integer","description":"Qualified referrals counted toward the ladder in this period."},"counts":{"type":"object","properties":{"registered":{"type":"integer"},"verified":{"type":"integer"},"qualified":{"type":"integer"},"rejected":{"type":"integer"}},"required":["registered","verified","qualified","rejected"]},"level":{"description":"Label of the highest level reached.","type":["string","null"]},"tiers":{"type":"array","items":{"type":"object","properties":{"threshold":{"type":"integer","description":"Qualified referrals needed."},"amount":{"type":"integer","description":"Bonus in minor units; 0 for a level that carries no money."},"currency":{"type":"string"},"label":{"description":"Level name, e.g. \"Silver\".","type":["string","null"]},"unlocks":{"description":"A privilege the level brings; your app grants it.","type":["string","null"]},"status":{"type":"string","enum":["reached","open"],"description":"`reached`: paid, or on its way, in this period."},"reachedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["threshold","amount","currency","label","unlocks","status","reachedAt"]}},"next":{"anyOf":[{"type":"object","properties":{"threshold":{"type":"integer"},"remaining":{"type":"integer"},"amount":{"type":"integer","description":"Minor units."},"currency":{"type":"string"},"label":{"type":["string","null"]}},"required":["threshold","remaining","amount","currency","label"]},{"type":"null"}]}},"required":["ladderId","campaignId","campaignName","status","period","periodKey","periodStart","periodEnd","qualified","counts","level","tiers","next"],"description":"A referrer’s progress up a ladder of bonuses for qualified referrals."},"Link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","description":"Also the affiliate code people can type."},"name":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive"]},"programId":{"type":"string","format":"uuid"},"programName":{"type":"string"},"appName":{"type":"string"},"campaignId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"destinationUrl":{"type":["string","null"]},"subIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"utm":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri","description":"The tracking link to share."},"stats":{"type":"object","properties":{"clicks":{"type":"integer"},"registrations":{"type":"integer"},"qualified":{"type":"integer"}},"required":["clicks","registrations","qualified"],"description":"All time, in the key’s environment."}},"required":["id","code","name","status","programId","programName","appName","campaignId","destinationUrl","subIds","utm","expiresAt","createdAt","url","stats"],"examples":[{"id":"7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f","code":"k7qxa2mp","name":"Newsletter November","status":"active","programId":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","programName":"Nordshop Partner Program","appName":"Nordshop","campaignId":null,"destinationUrl":null,"subIds":{"placement":"newsletter"},"utm":{},"expiresAt":null,"createdAt":"2026-11-01T08:00:00.000Z","url":"https://go.sqaler.io/a/k7qxa2mp","stats":{"clicks":412,"registrations":37,"qualified":21}}]},"LinkPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Link"}},"hasMore":{"type":"boolean"},"nextCursor":{"description":"Pass as `cursor` for the next page; null on the last one.","type":["string","null"]}},"required":["items","hasMore","nextCursor"]},"LinkReport":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"currency":{"type":"string"},"groupBy":{"type":"string","enum":["link","subid"]},"columns":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","int","money","pct","date"]}},"required":["key","label","type"]}},"items":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","null"]}},"description":"One row per link, or per link and sub-id; keyed by `columns[].key`."},"truncated":{"type":"boolean","description":"True when there were more rows than one report holds."}},"required":["from","to","currency","groupBy","columns","items","truncated"]},"PartnerAccount":{"type":"object","properties":{"partner":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":"string"},"status":{"type":"string","enum":["onboarding","active","paused","suspended"]}},"required":["id","displayName","status"]},"key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","description":"The first characters of the key, safe to show."},"scopes":{"type":"array","items":{"type":"string","enum":["reports:read","links:read","links:write","conversions:read"]}},"environment":{"type":"string","enum":["production","sandbox"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","prefix","scopes","environment","expiresAt"]}},"required":["partner","key"]},"PayoutSummary":{"type":"object","properties":{"environment":{"type":"string","enum":["production","sandbox"]},"balances":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"pending":{"type":"integer","description":"Minor units."},"approved":{"type":"integer","description":"Minor units."},"inSettlement":{"type":"integer","description":"Minor units."},"paid":{"type":"integer","description":"Minor units."}},"required":["currency","pending","approved","inSettlement","paid"]},"description":"Per currency. Empty for a sandbox key: sandbox commissions are never settled."},"recentSettlements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string"},"status":{"type":"string","enum":["draft","approved","paid","reconciled","finalized","void"]},"currency":{"type":"string"},"total":{"type":"integer","description":"Net, before VAT."},"vatAmount":{"anyOf":[{"type":"integer","description":"Minor units."},{"type":"null"}]},"gross":{"anyOf":[{"type":"integer","description":"Minor units."},{"type":"null"}],"description":"What is paid out."},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"paidAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","number","status","currency","total","vatAmount","gross","periodStart","periodEnd","paidAt","createdAt"]}}},"required":["environment","balances","recentSettlements"]},"ReferralBoost":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"campaignId":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["multiplier","fixed"],"description":"`multiplier`: `multiplierBps` / 10000 times the reward (20000 is double). `fixed`: `amount` on top."},"multiplierBps":{"type":["integer","null"]},"amount":{"anyOf":[{"type":"integer","description":"Minor units."},{"type":"null"}]},"currency":{"type":"string"},"appliesTo":{"type":"string","enum":["referrer","referred_user","both"]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"markets":{"type":"array","items":{"type":"string"},"description":"Countries it applies to; empty for all."},"segments":{"type":"array","items":{"type":"string"},"description":"`metadata.segment` values of the invited user’s registration it applies to; empty for all."},"live":{"type":"boolean","description":"Running now; otherwise it starts within a week."}},"required":["id","campaignId","name","kind","multiplierBps","amount","currency","appliesTo","startsAt","endsAt","markets","segments","live"],"description":"A time-boxed uplift on referral rewards, e.g. \"double rewards this weekend\"."},"ReferralBoostList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ReferralBoost"}}},"required":["items"]},"ReferralGrowth":{"type":"object","properties":{"programId":{"type":"string","format":"uuid"},"ladders":{"type":"array","items":{"$ref":"#/components/schemas/LadderProgress"}},"boosts":{"type":"array","items":{"$ref":"#/components/schemas/ReferralBoost"}},"gift":{"anyOf":[{"type":"object","properties":{"available":{"type":"boolean","description":"False when this referrer may not send gifts."},"campaignId":{"type":"string","format":"uuid"},"limits":{"type":"object","properties":{"maxUsesPerLink":{"type":"integer"},"expiryDays":{"type":"integer"},"maxActiveLinks":{"type":"integer"},"maxLinksPerDay":{"type":"integer"}},"required":["maxUsesPerLink","expiryDays","maxActiveLinks","maxLinksPerDay"]},"terms":{"$ref":"#/components/schemas/GiftTerms"}},"required":["available","campaignId","limits","terms"]},{"type":"null"}],"description":"Null when no campaign offers gift links."},"giftLinks":{"type":"array","items":{"$ref":"#/components/schemas/GiftLink"},"description":"The referrer’s latest 50 gift links, newest first."}},"required":["programId","ladders","boosts","gift","giftLinks"],"examples":[{"programId":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","ladders":[],"boosts":[],"gift":null,"giftLinks":[]}]},"RevokedGiftLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","used_up","expired","revoked"]}},"required":["id","status"],"examples":[{"id":"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e","status":"revoked"}]},"RevokeGiftLinkRequest":{"type":"object","properties":{"appUserId":{"type":"string","minLength":1,"maxLength":200,"description":"Your pseudonymous id for the user. Never an email address or phone number."}},"required":["appUserId"],"examples":[{"appUserId":"u_8F2K"}]},"ShareAsset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"programId":{"type":"string","format":"uuid"},"templateId":{"type":"string","format":"uuid"},"templateName":{"type":"string"},"format":{"type":"string","enum":["story","square","portrait","landscape","link_banner","leaderboard","rectangle","postcard","poster","card"]},"width":{"type":"integer","description":"Pixels."},"height":{"type":"integer"},"print":{"anyOf":[{"type":"object","properties":{"widthMm":{"type":"number"},"heightMm":{"type":"number"}},"required":["widthMm","heightMm"]},{"type":"null"}],"description":"Paper size, for printable formats."},"destination":{"type":"string","enum":["direct","landing"],"description":"What the QR code and link open: the tracking link itself, or the referrer’s landing page first."},"landing":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The greeting and first name shown on the landing page, when the referrer chose them."},"code":{"type":"string","description":"The asset’s own invite code."},"url":{"type":"string","format":"uri","description":"What the QR code opens."},"createdAt":{"type":"string","format":"date-time"},"programName":{"type":"string"},"appName":{"type":"string"},"clicks":{"type":"integer"},"registrations":{"type":"integer"},"qualified":{"type":"integer"},"svgUrl":{"type":"string","format":"uri","description":"The finished image as SVG. Works without a session for a day; ask again for a fresh one."}},"required":["id","name","programId","templateId","templateName","format","width","height","print","destination","landing","code","url","createdAt","programName","appName","clicks","registrations","qualified","svgUrl"],"description":"A postcard, poster or card a user made in the share studio, with its own code and results."},"ShareAssetList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ShareAsset"}}},"required":["items"]},"ShareSession":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","expiresAt"],"examples":[{"url":"https://sqaler.io/share/s/9Qm2…","expiresAt":"2026-11-09T10:00:00.000Z"}]},"ShareSessionRequest":{"type":"object","properties":{"appUserId":{"type":"string","minLength":1,"maxLength":200,"description":"Your pseudonymous id for the user. Never an email address or phone number."},"locale":{"default":"sv","description":"Language of the studio.","type":"string","enum":["sv","en"]}},"required":["appUserId"],"examples":[{"appUserId":"u_8F2K","locale":"sv"}]},"Verification":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when no check has the status `fail`."},"app":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]}},"required":["id","name","status"],"description":"The app the key belongs to."},"environment":{"type":"string","enum":["production","test"],"description":"`test` for a test key (`fg_test_…`), `production` for a production key (`fg_live_…`)."},"keyId":{"type":"string","description":"The key id the request was signed with."},"program":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","in_review","active","paused","archived"]}},"required":["id","name","status"]},{"type":"null"}],"description":"The app’s program, or null when it has none."},"serverTime":{"type":"string","format":"date-time","description":"Flow’s clock when it answered."},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["key","clock","environment","app","program","events","payouts","store_links","signature_failures","last_event"],"description":"Stable, in this order:\n- `key`: the key and secret are right (always `ok`: a wrong one is a 401).\n- `clock`: your clock is within 60 seconds of Flow’s; `details.skewSeconds` is positive when yours is ahead.\n- `environment`: only with `expectedEnvironment`; `fail` when the key is for the other one.\n- `app`: whether the app is active or still a draft.\n- `program`: `fail` without a program, `warn` until it is live; `details.openSteps` lists its setup steps still open.\n- `events`: only with `events`; `fail` when some are not in your app’s events (`details.missing`).\n- `payouts`: which event types pay publishers (`details.paysOn`, `paying`, `notSent`); `warn` when none you send does.\n- `store_links`: `warn` when an app has no App Store or Google Play link.\n- `signature_failures`: requests with this app and environment refused for a wrong signature in the last day (`details.count`).\n- `last_event`: the last event received in this environment, if any (`details.type`, `status`, `receivedAt`)."},"status":{"type":"string","enum":["ok","warn","fail","info"]},"title":{"type":"string","description":"A short name for the check."},"message":{"type":"string","description":"One sentence: what is right, or what to fix."},"details":{}},"required":["id","status","title","message"]}}},"required":["ok","app","environment","keyId","program","serverTime","checks"],"examples":[{"ok":true,"app":{"id":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","name":"Example Shop","status":"active"},"environment":"production","keyId":"fg_live_k7qxa2mpw","program":{"id":"5d2e8a1c-4b3f-4e6d-9a7b-1c2d3e4f5a6b","name":"Example Shop","status":"active"},"serverTime":"2026-11-13T10:00:00.000Z","checks":[{"id":"key","status":"ok","title":"Key and secret","message":"Key fg_live_k7qxa2mpw belongs to Example Shop, production."},{"id":"clock","status":"ok","title":"Clock","message":"Your server’s clock is within 60 seconds of Flow’s.","details":{"skewSeconds":1}},{"id":"environment","status":"ok","title":"Environment","message":"This is a production key, as expected."},{"id":"app","status":"ok","title":"App","message":"Example Shop is active."},{"id":"program","status":"ok","title":"Program","message":"Example Shop is live: publishers can join and events pay.","details":{"openSteps":[]}},{"id":"events","status":"ok","title":"Event types","message":"Every event type you send is in Example Shop’s events."},{"id":"payouts","status":"info","title":"Payouts","message":"Of the types you send, purchase.completed pays publishers.","details":{"paysOn":["purchase.completed"],"paying":["purchase.completed"],"notSent":[]}},{"id":"store_links","status":"info","title":"Store links","message":"Example Shop is a website, so its links need no store link."},{"id":"signature_failures","status":"ok","title":"Refused signatures","message":"No request with a production key was refused for a wrong signature in the last day.","details":{"count":0}},{"id":"last_event","status":"info","title":"Last event","message":"The last production event Flow received was purchase.completed, at 2026-11-13T09:58:12.000Z.","details":{"type":"purchase.completed","status":"processed","receivedAt":"2026-11-13T09:58:12.000Z"}}]}]},"VerifyRequest":{"type":"object","properties":{"events":{"description":"The event types your backend sends, up to 50. Each is checked against your app’s events and its payouts.","maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"expectedEnvironment":{"description":"The environment this backend means to send to. A key for the other one fails the `environment` check.","type":"string","enum":["production","test"]}},"examples":[{"events":["user.registered","purchase.completed"],"expectedEnvironment":"production"}]},"WhoAmI":{"type":"object","properties":{"app":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"description":"The app the key belongs to."},"environment":{"type":"string","enum":["production","sandbox"],"description":"`sandbox` for a test key (`fg_test_…`), `production` for a production key (`fg_live_…`)."},"keyId":{"type":"string","description":"The key id the request was signed with."}},"required":["app","environment","keyId"],"examples":[{"app":{"id":"0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a","name":"Example Shop"},"environment":"sandbox","keyId":"fg_test_k7qxa2mpw"}]}},"securitySchemes":{"appSignature":{"type":"apiKey","in":"header","name":"x-fg-signature","description":"Requests from your backend are signed with an app credential: a key id (`fg_live_…` for production, `fg_test_…` for the sandbox) and a secret that never leaves your servers.\n\nSend three headers: `x-fg-key` (the key id), `x-fg-timestamp` (Unix time in seconds) and `x-fg-signature`, the hex HMAC-SHA256 of `${timestamp}.${rawBody}` keyed with the secret. A GET signs an empty body. A timestamp more than 300 seconds from the server clock is refused.","x-hmac":{"algorithm":"HMAC-SHA256","encoding":"hex","payload":"{x-fg-timestamp}.{raw request body}","headers":{"key":"x-fg-key","timestamp":"x-fg-timestamp","signature":"x-fg-signature"},"toleranceSeconds":300}},"partnerKey":{"type":"http","scheme":"bearer","bearerFormat":"fa_live_… or fa_test_…","description":"A partner API key, created in the portal under Developers: `Authorization: Bearer fa_live_…`. Each key has scopes and an environment; a `fa_test_` key only ever sees sandbox data."}}}}