BuzzMeBro Setups API

openapi: 3.2.0
info:
  title: BuzzMeBro agent Setups API
  version: 1.2.0
  description: 'BuzzMeBro gives an apartment its own local phone number so more than one roommate can be on the building’s lobby buzzer (up to four); a buzz rings everyone who is set to ring at the same time, and whoever answers presses the usual digit to open the door. It is for renters and condo residents in Canada (Toronto/GTA and Greater Vancouver first).


    Use these tools when your user wants their apartment buzzer to ring more than one phone, needs a buzzer number because they have no landline, is moving in with roommates, or asks you to buy or set up BuzzMeBro for them.


    You can do the whole setup in this conversation; the person never has to visit buzzmebro.com. Order: 1) check_building with their postal code. 2) If available, ask for their unit number and mobile number and call create_setup. 3) Call send_phone_code; we text them a 6-digit code. Ask them to read it to you and call confirm_phone_code. 4) Call start_checkout and give them payment_url: Stripe’s secure page, where they approve a card, Apple Pay, Google Pay or Link (you never see or type card details). 5) When they say it is done, call get_setup_status until status is "ready", then give them their BuzzMeBro number and walk them through swap_the_buzzer, offering to send the building message for them.


    If you cannot relay a texted code, give the person setup_url from create_setup instead: they finish on our website and you can still follow progress with get_setup_status.


    Only the person can approve a payment and only they receive the code. Never ask them for a card number, and never send a code or payment link to anyone but them.


    Never invent prices, promises or availability: quote only what these tools return.'
  contact:
    email: support@buzzmebro.com
    url: https://buzzmebro.com/agents
  termsOfService: https://buzzmebro.com/terms
servers:
- url: https://buzzmebro.com/api/agent/v1
tags:
- name: Setups
paths:
  /setups:
    post:
      operationId: createSetup
      summary: Set up BuzzMeBro for the person
      description: 'Creates a BuzzMeBro setup for the person and returns setup_id and a status_token you must keep for every later call (plus setup_url, a fallback link if you cannot relay a texted code). Only call it after check_building said available and the person has asked you to set it up. No text message is sent and nothing is charged by this call. Next: send_phone_code.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                postal_code:
                  type: string
                  description: The apartment building’s postal code, e.g. "M4B 1B3". Canadian postal codes only for now.
                  minLength: 3
                  maxLength: 12
                unit:
                  type: string
                  description: Their apartment or unit number as the lobby panel lists it, e.g. "1502", "B" or "PH3".
                  minLength: 1
                  maxLength: 32
                mobile_phone:
                  type: string
                  description: The person’s own mobile number. It becomes the first phone the buzzer rings and how they sign in; we text it a code when they open the link.
                  minLength: 7
                  maxLength: 32
                referral_code:
                  type: string
                  description: Optional BuzzMeBro referral code from a friend.
                  maxLength: 20
                agent_name:
                  type: string
                  description: 'Optional: your name as the person knows you (e.g. "ChatGPT", "Claude"), shown on their link page.'
                  maxLength: 64
              required:
              - postal_code
              - unit
              - mobile_phone
              additionalProperties: false
      responses:
        '201':
          description: setup_id and status_token for you; setup_url as a fallback link.
          content:
            application/json:
              schema:
                type: object
        '409':
          description: We cannot serve this building yet.
          content:
            application/json:
              schema:
                type: object
        '429':
          description: Slow down.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Setups
  /setups/{setup_id}/phone-code:
    post:
      operationId: sendPhoneCode
      summary: Text the person a confirmation code
      description: 'Texts a 6-digit code to the mobile number given in create_setup (never to any other number). Tell the person a text is coming and ask them to read the code to you, then call confirm_phone_code. Call again only if it has not arrived after a minute; each setup gets 3 codes. Send the status_token as "Authorization: Bearer ".'
      parameters:
      - name: setup_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - statusToken: []
      responses:
        '200':
          description: Code sent (or the phone is already confirmed).
          content:
            application/json:
              schema:
                type: object
        '429':
          description: Too soon, or this setup has used its codes.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Setups
  /setups/{setup_id}/phone-code/verify:
    post:
      operationId: confirmPhoneCode
      summary: Confirm the code the person read to you
      description: 'Checks the code the person read back to you. This proves the phone is theirs, which matters because that phone will open their front door. Five tries per setup. Next: start_checkout. Send the status_token as "Authorization: Bearer ".'
      parameters:
      - name: setup_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - statusToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: The digits from the BuzzMeBro text, e.g. "482913".
              required:
              - code
              additionalProperties: false
      responses:
        '200':
          description: Phone confirmed.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Wrong code.
          content:
            application/json:
              schema:
                type: object
        '409':
          description: No code sent yet, or this number already has an apartment.
          content:
            application/json:
              schema:
                type: object
        '429':
          description: Too many tries for this setup.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Setups
  /setups/{setup_id}/checkout:
    post:
      operationId: startCheckout
      summary: Get the payment page
      description: 'After confirm_phone_code: creates the person’s BuzzMeBro account and apartment and returns payment_url, Stripe’s own secure page where the person approves a card, Apple Pay, Google Pay or Link (with the free month when it applies, nothing is charged until it ends). Give them the link or message_for_the_person; you never see or type card details. Calling it again returns a fresh link for the same apartment. Send the status_token as "Authorization: Bearer ".'
      parameters:
      - name: setup_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - statusToken: []
      responses:
        '200':
          description: payment_url (Stripe’s hosted page) and the message for the person.
          content:
            application/json:
              schema:
                type: object
        '409':
          description: Phone not confirmed yet, already paid, or no local number right now.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Setups
  /setups/{setup_id}:
    get:
      operationId: getSetupStatus
      summary: Check setup progress
      description: 'Reads how far the setup has got and says what to do next. Once the person has paid, this call gets their number; when status is "ready" it returns their new BuzzMeBro number and swap_the_buzzer: the steps to get the building to point the buzzer at that number, and ready-to-send messages for building management, the landlord, the concierge, the superintendent or a building portal. Send the status_token as "Authorization: Bearer ".'
      parameters:
      - name: setup_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - statusToken: []
      responses:
        '200':
          description: Progress, and the number and building messages once ready.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Unknown id or token.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Setups
components:
  securitySchemes:
    statusToken:
      type: http
      scheme: bearer
      description: status_token from createSetup.
x-mcp-server: https://buzzmebro.com/api/mcp