BuzzMeBro Applications API

openapi: 3.2.0
info:
  title: BuzzMeBro partner Applications API
  version: 1.0.0
  description: 'BuzzMeBro partners (front desk and concierge staff, property managers, condo boards, leasing agents, movers, student housing offices) share a link with renters. Every apartment that signs up through their link or code pays the partner 50% of what that apartment pays BuzzMeBro (after sales tax, refunds, chargebacks and Stripe’s fee), every month, for as long as it stays. Only money actually collected counts: nothing on signups or free months. Only direct referrals: never on friends those apartments refer. Canada only for now.


    Order: partner_program_info, then partner_apply, partner_send_code (we text the person a code; ask them to read it to you), partner_confirm_code, partner_terms_link (the PERSON opens it and accepts the terms themselves), then partner_claim_key once to receive their partner key. With the key: partner_get_links, partner_get_kit, partner_get_stats, partner_payout_link (Stripe’s own page where the PERSON adds their bank, once they have money ready), partner_rotate_key.


    Send the partner key only as "Authorization: Bearer " (REST) or in the partner_key argument (MCP), never in a URL. Never invent earnings: say only what partner_get_stats returns, and never promise income.'
  contact:
    email: support@buzzmebro.com
    url: https://buzzmebro.com/partners
  termsOfService: https://buzzmebro.com/partners/terms
servers:
- url: https://buzzmebro.com/api/partner/v1
tags:
- name: Applications
paths:
  /applications:
    post:
      operationId: partnerApply
      summary: Start a partner application for the person
      description: 'Starts a partner application with the person’s details and returns application_id and application_token. Only call it when the person has asked to join. No text is sent by this call. Next: partner_send_code.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Refused, with an error sentence.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                  description: The person’s name.
                mobile_phone:
                  type: string
                  minLength: 7
                  maxLength: 32
                  description: The person’s own Canadian mobile number. We text it a code.
                email:
                  type: string
                  maxLength: 254
                  description: The person’s email.
                persona:
                  type: string
                  enum:
                  - front_desk
                  - property_manager
                  - condo_board
                  - leasing_agent
                  - mover
                  - student_housing
                  - tenant_insurance
                  - co_living
                  - telecom
                  - listing_site
                  - relocation
                  - landlord
                  - move_in_service
                  - delivery
                  - creator
                  - other
                  description: 'The partner type: how they meet renters (front desk or building staff, leasing agent, mover, tenant insurance, co-living, university, telecom, listing site, relocation, landlord, move-in service, delivery).'
                payouts_off:
                  type: boolean
                  description: 'Optional: true for organisations that cannot take money (for example a university or a settlement agency). Their residents still get the perk; no payouts are ever made.'
                building:
                  type: string
                  maxLength: 120
                  description: 'Optional: the building or company they work with.'
                employer_ok:
                  type: boolean
                  description: 'If they work for a building or concierge company: has their employer allowed it?'
              required:
              - name
              - mobile_phone
              - email
              - persona
              additionalProperties: false
      tags:
      - Applications
  /applications/{application_id}/code:
    post:
      operationId: partnerSendCode
      summary: Text the person a confirmation code
      description: Texts a 6-digit code to the mobile number in the application (never any other number). Ask the person to read it to you, then call partner_confirm_code. Each application gets 3 codes, at least a minute apart.
      parameters:
      - name: application_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Refused, with an error sentence.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                application_token:
                  type: string
                  description: application_token from partner_apply. Keep it private; it collects the partner key once.
              required:
              - application_token
              additionalProperties: false
      tags:
      - Applications
  /applications/{application_id}/code/verify:
    post:
      operationId: partnerConfirmCode
      summary: Confirm the code the person read to you
      description: 'Checks the texted code. Five tries per application. Next: partner_terms_link.'
      parameters:
      - name: application_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Refused, with an error sentence.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                application_token:
                  type: string
                  description: application_token from partner_apply. Keep it private; it collects the partner key once.
                code:
                  type: string
                  description: The digits from the text.
              required:
              - application_token
              - code
              additionalProperties: false
      tags:
      - Applications
  /applications/{application_id}/terms-link:
    post:
      operationId: partnerTermsLink
      summary: Get the terms page for the person
      description: 'Returns a one-time link to the partner terms. Give it to the person: they read the terms and press Accept themselves. You cannot accept for them. When they say it is done, call partner_claim_key.'
      parameters:
      - name: application_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Refused, with an error sentence.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                application_token:
                  type: string
                  description: application_token from partner_apply. Keep it private; it collects the partner key once.
              required:
              - application_token
              additionalProperties: false
      tags:
      - Applications
  /applications/{application_id}/key:
    post:
      operationId: partnerClaimKey
      summary: Collect the partner key (once)
      description: 'After the person accepted the terms: returns their partner link, code and partner key. The key is shown once; keep it private and use it for the partner_get_* tools. The application token stops working after this call.'
      parameters:
      - name: application_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Refused, with an error sentence.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                application_token:
                  type: string
                  description: application_token from partner_apply. Keep it private; it collects the partner key once.
              required:
              - application_token
              additionalProperties: false
      tags:
      - Applications
components:
  securitySchemes:
    partnerKey:
      type: http
      scheme: bearer
      description: The partner key from partner_claim_key.