{"openapi":"3.1.0","info":{"title":"ReferralCodes Agent API","version":"1.0.0","description":"Search ReferralCodes.com for member-shared referral offers (sign-up bonuses, refer-a-friend rewards). Search first, then call get_referral_link only for the offer the user picks. Rewards are as listed by the brand or stated by the member; never promise eligibility."},"servers":[{"url":"https://rewardcircle.com/api/agent/v1"}],"paths":{"/referrals":{"get":{"operationId":"search_referrals","summary":"Search referral offers","description":"Find member-shared referral offers (sign-up bonuses, refer-a-friend rewards) on ReferralCodes.com by brand, product category or a natural-language request such as \"bank account UK\". Returns ranked offers with opaque referral_id values; it never returns raw codes or links. Call get_referral_link for the offer the user chooses. scope \"contacts\" or \"all\" searches referrals from people the signed-in member follows and requires the member to connect their account. Rewards are as stated by the member or listed by the brand and are not verified.","parameters":[{"name":"query","in":"query","required":false,"description":"What the user is looking for, e.g. \"Monzo\", \"energy supplier UK\", \"cashback app\".","schema":{"type":"string","maxLength":200}},{"name":"brand","in":"query","required":false,"description":"Exact brand name or website, if known, e.g. \"Octopus Energy\" or \"octopus.energy\".","schema":{"type":"string","maxLength":100}},{"name":"category","in":"query","required":false,"description":"Product category, e.g. \"banking\", \"energy\", \"travel\".","schema":{"type":"string","maxLength":100}},{"name":"country","in":"query","required":false,"description":"Country name or ISO 3166 code where the user lives, e.g. \"UK\", \"United States\", \"DE\".","schema":{"type":"string","maxLength":60}},{"name":"scope","in":"query","required":false,"description":"\"public\" (default): all members' public referrals. \"contacts\": only people the member follows. \"all\": both, returned separately.","schema":{"type":"string","enum":["public","contacts","all"],"default":"public"}},{"name":"limit","in":"query","required":false,"description":"Maximum referrals per group.","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}}],"security":[{},{"oauth2":["referrals:read"]}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","no_match","no_contacts","error"]},"scope":{"type":"string"},"search":{"type":"object"},"interpreted":{"type":"object"},"public":{"type":"array","items":{"type":"object","properties":{"referral_id":{"type":"string"},"brand":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":["string","null"]},"listing_url":{"type":"string"}}},"title":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["code","link"]},"countries":{"type":"array","items":{"type":"string"}},"rewards":{"type":"object","properties":{"member_stated":{"type":["string","null"]},"brand_listed":{"type":["object","null"],"properties":{"you_get":{"type":["string","null"]},"referrer_gets":{"type":["string","null"]}}},"verified":{"type":"boolean"}}},"relationship":{"type":"string","enum":["public","contact"]},"shared_by":{"type":"object","properties":{"display_name":{"type":"string"},"username":{"type":"string"}}},"promoted":{"type":"boolean"},"availability":{"type":"string"},"link_available":{"type":"boolean"},"listing_url":{"type":"string"},"updated_at":{"type":["string","null"]}},"required":["referral_id","brand","title","relationship"]}},"contacts":{"type":"array","items":{"type":"object","properties":{"referral_id":{"type":"string"},"brand":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":["string","null"]},"listing_url":{"type":"string"}}},"title":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["code","link"]},"countries":{"type":"array","items":{"type":"string"}},"rewards":{"type":"object","properties":{"member_stated":{"type":["string","null"]},"brand_listed":{"type":["object","null"],"properties":{"you_get":{"type":["string","null"]},"referrer_gets":{"type":["string","null"]}}},"verified":{"type":"boolean"}}},"relationship":{"type":"string","enum":["public","contact"]},"shared_by":{"type":"object","properties":{"display_name":{"type":"string"},"username":{"type":"string"}}},"promoted":{"type":"boolean"},"availability":{"type":"string"},"link_available":{"type":"boolean"},"listing_url":{"type":"string"},"updated_at":{"type":["string","null"]}},"required":["referral_id","brand","title","relationship"]}},"note":{"type":"string"},"error":{"type":"object","description":"Present only when status is \"error\".","properties":{"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","PERMISSION_DENIED","REFERRAL_NOT_FOUND","REFERRAL_UNAVAILABLE","CONTACT_NOT_FOUND","AMBIGUOUS_CONTACT","VALIDATION_FAILED","DUPLICATE_REFERRAL","RATE_LIMIT_EXCEEDED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["status"]}}}},"401":{"description":"AUTHENTICATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"PERMISSION_DENIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"REFERRAL_NOT_FOUND, CONTACT_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"AMBIGUOUS_CONTACT, DUPLICATE_REFERRAL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"REFERRAL_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/referrals/{referral_id}":{"get":{"operationId":"get_referral","summary":"Get referral details","description":"Get the full details of one referral offer returned by search_referrals: rewards, eligible countries, conditions and terms. Does not return the code or link; use get_referral_link for that.","parameters":[{"name":"referral_id","in":"path","required":true,"description":"Opaque referral ID from search_referrals, e.g. \"ref_3kTq9...\".","schema":{"type":"string","maxLength":64}}],"security":[{},{"oauth2":["referrals:read"]}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"referral":{"type":"object","properties":{"referral_id":{"type":"string"},"brand":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":["string","null"]},"listing_url":{"type":"string"}}},"title":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["code","link"]},"countries":{"type":"array","items":{"type":"string"}},"rewards":{"type":"object","properties":{"member_stated":{"type":["string","null"]},"brand_listed":{"type":["object","null"],"properties":{"you_get":{"type":["string","null"]},"referrer_gets":{"type":["string","null"]}}},"verified":{"type":"boolean"}}},"relationship":{"type":"string","enum":["public","contact"]},"shared_by":{"type":"object","properties":{"display_name":{"type":"string"},"username":{"type":"string"}}},"promoted":{"type":"boolean"},"availability":{"type":"string"},"link_available":{"type":"boolean"},"listing_url":{"type":"string"},"updated_at":{"type":["string","null"]},"terms":{"type":["string","null"]},"conditions":{"type":["object","null"]},"category":{"type":["string","null"]}},"required":["referral_id","brand","title","relationship"]},"error":{"type":"object","description":"Present only when status is \"error\".","properties":{"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","PERMISSION_DENIED","REFERRAL_NOT_FOUND","REFERRAL_UNAVAILABLE","CONTACT_NOT_FOUND","AMBIGUOUS_CONTACT","VALIDATION_FAILED","DUPLICATE_REFERRAL","RATE_LIMIT_EXCEEDED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["status"]}}}},"401":{"description":"AUTHENTICATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"PERMISSION_DENIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"REFERRAL_NOT_FOUND, CONTACT_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"AMBIGUOUS_CONTACT, DUPLICATE_REFERRAL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"REFERRAL_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/referrals/{referral_id}/link":{"post":{"operationId":"get_referral_link","summary":"Get referral link","description":"Get the link (and code, if the offer has one) for a referral offer the user has chosen. Returns a ReferralCodes.com link that redirects to the member's referral; share it with the user as-is. Pass the user's country to check whether the offer is listed as available there. Only call this after the user picks an offer.","parameters":[{"name":"referral_id","in":"path","required":true,"description":"Opaque referral ID from search_referrals, e.g. \"ref_3kTq9...\".","schema":{"type":"string","maxLength":64}}],"security":[{},{"oauth2":["referrals:read"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","maxLength":60,"description":"Country name or ISO 3166 code where the user lives, e.g. \"UK\", \"United States\", \"DE\"."}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"referral_id":{"type":"string"},"brand":{"type":"string"},"referral_url":{"type":"string","format":"uri"},"url_type":{"type":"string","enum":["referralcodes_redirect"]},"referral_code":{"type":"string"},"destination_domain":{"type":"string"},"how_to_use":{"type":"string"},"reward_summary":{"type":"string"},"conditions_summary":{"type":"string"},"country_eligibility":{"type":"string","enum":["listed","not_listed","unknown"]},"listing_url":{"type":"string"},"expires_at":{"type":"string"},"error":{"type":"object","description":"Present only when status is \"error\".","properties":{"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","PERMISSION_DENIED","REFERRAL_NOT_FOUND","REFERRAL_UNAVAILABLE","CONTACT_NOT_FOUND","AMBIGUOUS_CONTACT","VALIDATION_FAILED","DUPLICATE_REFERRAL","RATE_LIMIT_EXCEEDED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["status"]}}}},"401":{"description":"AUTHENTICATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"PERMISSION_DENIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"REFERRAL_NOT_FOUND, CONTACT_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"AMBIGUOUS_CONTACT, DUPLICATE_REFERRAL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"REFERRAL_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/referrals":{"get":{"operationId":"search_contacts_referrals","summary":"Search referrals from people I follow","description":"Find referral offers shared by the people the signed-in member follows on ReferralCodes (\"contacts\"). Optionally narrow to one contact by name or username, and/or to a brand, category or request. With no filters, lists the newest referrals from all contacts. Requires the member to connect their ReferralCodes account and allow access to their contacts. If the contact name matches several people, the error lists the candidates so you can ask the user which one.","parameters":[{"name":"contact","in":"query","required":false,"description":"Name or username of one person the member follows, e.g. \"Sarah\" or \"sarah_j\".","schema":{"type":"string","maxLength":100}},{"name":"query","in":"query","required":false,"description":"What the user is looking for, e.g. \"energy supplier\".","schema":{"type":"string","maxLength":200}},{"name":"brand","in":"query","required":false,"description":"Brand name or website, e.g. \"Monzo\".","schema":{"type":"string","maxLength":100}},{"name":"category","in":"query","required":false,"description":"Product category, e.g. \"banking\".","schema":{"type":"string","maxLength":100}},{"name":"country","in":"query","required":false,"description":"Country name or ISO 3166 code where the user lives, e.g. \"UK\", \"United States\", \"DE\".","schema":{"type":"string","maxLength":60}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":5}}],"security":[{"oauth2":["contacts:read"]}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","no_match","no_contacts","error"]},"source":{"type":"string"},"search":{"type":"object"},"interpreted":{"type":"object"},"contact":{"type":"object","properties":{"display_name":{"type":"string"},"username":{"type":"string"}}},"total_matches":{"type":"integer"},"referrals":{"type":"array","items":{"type":"object","properties":{"referral_id":{"type":"string"},"brand":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":["string","null"]},"listing_url":{"type":"string"}}},"title":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string","enum":["code","link"]},"countries":{"type":"array","items":{"type":"string"}},"rewards":{"type":"object","properties":{"member_stated":{"type":["string","null"]},"brand_listed":{"type":["object","null"],"properties":{"you_get":{"type":["string","null"]},"referrer_gets":{"type":["string","null"]}}},"verified":{"type":"boolean"}}},"relationship":{"type":"string","enum":["public","contact"]},"shared_by":{"type":"object","properties":{"display_name":{"type":"string"},"username":{"type":"string"}}},"promoted":{"type":"boolean"},"availability":{"type":"string"},"link_available":{"type":"boolean"},"listing_url":{"type":"string"},"updated_at":{"type":["string","null"]}},"required":["referral_id","brand","title","relationship"]}},"note":{"type":"string"},"error":{"type":"object","description":"Present only when status is \"error\".","properties":{"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","PERMISSION_DENIED","REFERRAL_NOT_FOUND","REFERRAL_UNAVAILABLE","CONTACT_NOT_FOUND","AMBIGUOUS_CONTACT","VALIDATION_FAILED","DUPLICATE_REFERRAL","RATE_LIMIT_EXCEEDED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["status"]}}}},"401":{"description":"AUTHENTICATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"PERMISSION_DENIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"REFERRAL_NOT_FOUND, CONTACT_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"AMBIGUOUS_CONTACT, DUPLICATE_REFERRAL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"REFERRAL_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/referrals":{"post":{"operationId":"import_my_referrals","summary":"Add my referral codes","description":"Add the signed-in member's own referral codes or links to their ReferralCodes profile. Only submit referrals the user has asked you to add and that belong to them. Each one is checked with the same rules as the ReferralCodes website and then reviewed before it is published, so a successful submission (\"requires_review\") is not yet public. Use dry_run to check a list before submitting it. Requires the member to connect their account and allow adding referrals.","security":[{"oauth2":["referrals:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"referrals":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","properties":{"brand":{"type":"string","minLength":1,"maxLength":255,"description":"Brand name or website, e.g. \"Monzo\" or \"monzo.com\"."},"code":{"type":"string","maxLength":255,"description":"The member's referral code, if the brand uses codes."},"url":{"type":"string","maxLength":255,"description":"The member's personal referral link (http or https)."},"reward":{"type":"string","minLength":1,"maxLength":50,"description":"What the friend gets, as the member describes it, e.g. \"\u00a320 when you open an account\"."},"description":{"type":"string","maxLength":1000,"description":"Optional terms or extra details from the member."}},"required":["brand","reward"],"additionalProperties":false},"description":"Referrals to add. Each needs a brand, a reward, and a code and/or link."},"dry_run":{"type":"boolean","default":false,"description":"Check the referrals without saving anything."}},"required":["referrals"]}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["submitted","nothing_submitted","dry_run","error"]},"dry_run":{"type":"boolean"},"summary":{"type":"object","properties":{"submitted":{"type":"integer"},"requires_review":{"type":"integer"},"duplicate":{"type":"integer"},"rejected":{"type":"integer"},"failed":{"type":"integer"},"valid":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"brand":{"type":["string","null"]},"matched_brand":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":["string","null"]},"listing_url":{"type":"string"}}},{"type":"null"}]},"status":{"type":"string","enum":["requires_review","duplicate","rejected","failed","valid"]},"referral_id":{"type":["string","null"]},"duplicate":{"type":"string","enum":["none","exact","same_request","awaiting_review","recently_removed","replaces_existing","similar_listing"]},"messages":{"type":"array","items":{"type":"string"}},"listing_url":{"type":["string","null"],"description":"Set once the referral is public; null while it awaits review."}},"required":["index","status","duplicate","messages"]}},"note":{"type":"string"},"error":{"type":"object","description":"Present only when status is \"error\".","properties":{"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","PERMISSION_DENIED","REFERRAL_NOT_FOUND","REFERRAL_UNAVAILABLE","CONTACT_NOT_FOUND","AMBIGUOUS_CONTACT","VALIDATION_FAILED","DUPLICATE_REFERRAL","RATE_LIMIT_EXCEEDED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["status"]}}}},"401":{"description":"AUTHENTICATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"PERMISSION_DENIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"REFERRAL_NOT_FOUND, CONTACT_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"AMBIGUOUS_CONTACT, DUPLICATE_REFERRAL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"REFERRAL_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TEMPORARILY_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"object","description":"Present only when status is \"error\".","properties":{"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","PERMISSION_DENIED","REFERRAL_NOT_FOUND","REFERRAL_UNAVAILABLE","CONTACT_NOT_FOUND","AMBIGUOUS_CONTACT","VALIDATION_FAILED","DUPLICATE_REFERRAL","RATE_LIMIT_EXCEEDED","TEMPORARILY_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["status","error"]}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"Authorization code flow with PKCE (S256). Public referral search works without a token.","flows":{"authorizationCode":{"authorizationUrl":"https://referralcodes.com/oauth/authorize","tokenUrl":"https://referralcodes.com/oauth/token","refreshUrl":"https://referralcodes.com/oauth/token","scopes":{"referrals:read":"Search and view referral offers on your behalf","contacts:read":"See referral offers shared by people you follow","referrals:write":"Add referral codes to your ReferralCodes profile (they are reviewed before going live)"}}}}}}}