{"openapi":"3.1.0","info":{"title":"FirstPromoter (BYOK) API","version":"0.1.0","description":"FirstPromoter (BYOK) lets an AI assistant read your own FirstPromoter data through the FirstPromoter API with a key you supply (API key (Settings, Integrations, Manage API Keys)). Read-only: 9 tools (list_promoters, get_promoter, list_referrals, get_referral, list_commissions, list_payouts, get_due_payout_stats, list_promoter_campaigns, list_promo_codes). The BYOK key travels with each request,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-firstpromoter.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-firstpromoter/docs"},"termsOfService":"https://connectorbay.com/byok-firstpromoter/terms"},"servers":[{"url":"https://byok-firstpromoter.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-firstpromoter/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_promoters":{"post":{"operationId":"list_promoters","summary":"List promoters (affiliates) with click, referral, customer, sale and revenue totals, optionally searched by email, name ","description":"List promoters (affiliates) with click, referral, customer, sale and revenue totals, optionally searched by email, name or reference id. Use for \"Who are my top FirstPromoter promoters\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against promoter email, name and reference id.","title":"Q"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (25 by default; the campaigns-style limit of 50 is a safe maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_promotersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_promoter":{"post":{"operationId":"get_promoter","summary":"Get one promoter by numeric id, or by email, customer id or promo code with find_by. Use for \"Show FirstPromoter promote","description":"Get one promoter by numeric id, or by email, customer id or promo code with find_by. Use for \"Show FirstPromoter promoter 1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Promoter numeric id, or the value of the attribute chosen in find_by (for example an email address).","maxLength":200,"title":"Id","type":"string"},"find_by":{"anyOf":[{"enum":["email","cust_id","auth_token","ref_token","promo_code"],"type":"string"},{"type":"null"}],"default":null,"description":"Treat id as this attribute instead of the numeric id.","title":"Find By"}},"required":["id"],"title":"get_promoterArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_referrals":{"post":{"operationId":"list_referrals","summary":"List referrals (leads and customers brought in by promoters) with state, promoter and campaign, optionally filtered by t","description":"List referrals (leads and customers brought in by promoters) with state, promoter and campaign, optionally filtered by type, state, promoter or creation dates. Use for \"Which FirstPromoter referrals became active customers\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against email, uid, username and website.","title":"Q"},"type":{"anyOf":[{"enum":["lead","customer"],"type":"string"},{"type":"null"}],"default":null,"description":"Only leads or only customers.","title":"Type"},"state":{"anyOf":[{"enum":["subscribed","signup","active","cancelled","refunded","denied","pending","moved"],"type":"string"},{"type":"null"}],"default":null,"description":"Only referrals in this state.","title":"State"},"promoter_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only referrals of this promoter id.","title":"Promoter Id"},"created_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only referrals created on or after this day, YYYY-MM-DD.","title":"Created From"},"created_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only referrals created on or before this day, YYYY-MM-DD.","title":"Created To"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (25 by default; the campaigns-style limit of 50 is a safe maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_referralsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_referral":{"post":{"operationId":"get_referral","summary":"Get one referral by numeric id, or by email, uid or username with find_by. Use for \"Show FirstPromoter referral for emai","description":"Get one referral by numeric id, or by email, uid or username with find_by. Use for \"Show FirstPromoter referral for email jane@example.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Referral numeric id, or the value of the attribute chosen in find_by (for example an email address).","maxLength":200,"title":"Id","type":"string"},"find_by":{"anyOf":[{"enum":["email","uid","username"],"type":"string"},{"type":"null"}],"default":null,"description":"Treat id as this attribute instead of the numeric id.","title":"Find By"}},"required":["id"],"title":"get_referralArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_commissions":{"post":{"operationId":"list_commissions","summary":"List commissions with status, amount, sale amount, paid flag, promoter, campaign and referral. Amounts are in the smalle","description":"List commissions with status, amount, sale amount, paid flag, promoter, campaign and referral. Amounts are in the smallest currency unit of the account. Use for \"Which FirstPromoter commissions are still pending approval\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against event id, referral email and referral uid.","title":"Q"},"status":{"anyOf":[{"enum":["pending","approved","denied"],"type":"string"},{"type":"null"}],"default":null,"description":"Only commissions with this status.","title":"Status"},"promoter_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only commissions of this promoter id.","title":"Promoter Id"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (25 by default; the campaigns-style limit of 50 is a safe maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_commissionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_payouts":{"post":{"operationId":"list_payouts","summary":"List payouts with status, amount, period, payout method, promoter and campaign, optionally by status, promoter or whethe","description":"List payouts with status, amount, period, payout method, promoter and campaign, optionally by status, promoter or whether they are payable. Use for \"Which FirstPromoter payouts are pending\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["pending","completed","failed","processing","cancelled"],"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts with this status.","title":"Status"},"promoter_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only payouts of this promoter id.","title":"Promoter Id"},"only_payable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to show only payable payouts.","title":"Only Payable"},"payout_method":{"anyOf":[{"enum":["paypal","bank","wise","crypto","custom","dots","not_set"],"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts using this method.","title":"Payout Method"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (25 by default; the campaigns-style limit of 50 is a safe maximum).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_payoutsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_due_payout_stats":{"post":{"operationId":"get_due_payout_stats","summary":"Show how many promoters and how much money fall in the next, overdue and custom payout periods, with the payout cycle se","description":"Show how many promoters and how much money fall in the next, overdue and custom payout periods, with the payout cycle settings. Use for \"How much do I owe FirstPromoter promoters right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_due_payout_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_promoter_campaigns":{"post":{"operationId":"list_promoter_campaigns","summary":"List the links between promoters and campaigns (which promoter promotes which campaign). Use for \"Which promoters run wh","description":"List the links between promoters and campaigns (which promoter promotes which campaign). Use for \"Which promoters run which FirstPromoter campaigns\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_promoter_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_promo_codes":{"post":{"operationId":"list_promo_codes","summary":"List promo codes with the reward they grant, the promoter campaign they belong to and archive time. Use for \"What promo ","description":"List promo codes with the reward they grant, the promoter campaign they belong to and archive time. Use for \"What promo codes exist in FirstPromoter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"promoter_campaign_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only codes of this promoter campaign id.","title":"Promoter Campaign Id"}},"title":"list_promo_codesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}