Bezal Requests API

openapi: 3.2.0
info:
  title: Bezal Public Requests API
  description: 'Search Bezal''s local business directory, view public business profiles, and send

    service requests to businesses.


    ## Authentication

    Pass your API key in the Authorization header (or in X-API-Key):

    ```

    Authorization: Bearer bzl_your_key_here

    ```

    Read endpoints (search, business details, categories, health, this spec) work without a key

    and are limited per IP. Write endpoints (requests) require a valid API key.

    Get a key at https://bezal.ai/developers/keys.


    ## What a business record contains

    Every business record has the same public shape. Contact details depend on the provider''s

    Bezal plan:

    - Always: id, name, category, city, state, avg_rating, review_count, tier, quote_request_url

    - Pro, Business and Premium plans: phone, website, address, zip, hours, photos, lat, lng

    - Business and Premium plans: description

    - Free and unclaimed listings: upgrade_note


    quote_request_url is the business''s public Bezal profile, where a person can send a request.


    ## Rate limiting

    Each key has a daily request limit, and anonymous callers have a daily limit per IP.

    When a limit is exceeded, the API returns 429.'
  version: 1.1.0
  contact:
    name: Bezal API Support
    url: https://bezal.ai/developers
servers:
- url: https://bezal.ai/api/v1
  description: Production
tags:
- name: Requests
paths:
  /requests:
    post:
      operationId: createQuoteRequest
      summary: Send a service request
      description: 'Send a service request to a business on behalf of a person. Requires a valid API key.

        The response''s `delivered` is true only when the business owner was notified. A request to

        a business that hasn''t claimed its Bezal profile is saved, but nobody is notified.'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - seeker_name
              - seeker_email
              - message
              properties:
                business_id:
                  type: string
                  format: uuid
                  description: Target business UUID. Without one, the request can't be delivered.
                seeker_name:
                  type: string
                  maxLength: 120
                seeker_email:
                  type: string
                  format: email
                seeker_phone:
                  type: string
                  maxLength: 40
                message:
                  type: string
                  maxLength: 4000
      responses:
        '201':
          description: Request saved
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - id
                - delivered
                properties:
                  success:
                    type: boolean
                  id:
                    type: string
                    format: uuid
                  delivered:
                    type: boolean
                    description: True only when the business owner was notified
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '404':
          description: Business not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Requests
components:
  responses:
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal server error
    InvalidKey:
      description: The API key is missing, malformed or inactive
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: Invalid API key
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: Rate limit exceeded
  schemas:
    RateLimitError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        tier:
          type: string
        requests_today:
          type: integer
        limit:
          type: integer
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bzl_...
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key