openapi: 3.0.0
info:
  title: HomeSpotter Boost Checkout API
  description: API for integrating with HomeSpotter's Boost platform to create and manage social media advertising campaigns for real estate listings and agent promotions.
  version: 2.0.0
  contact:
    name: HomeSpotter Support
  x-logo:
    url: 'https://docs.homespotter.com/images/logo-80a9c5e5.png'

servers:
  - url: 'https://boost.homespotter.com'
    description: Production environment for Boost Integration V1 & V2
    x-environment: production
  - url: 'https://boost.homespotter.com'
    description: QA/Staging environment (available upon request)
    x-environment: staging
    x-note: Contact Boost team for QA endpoint details
  - url: 'https://api.homespotter.com'
    description: GraphQL API server for agent lookups and queries
    x-environment: production

security:
  - jwt_token: []

tags:
  - name: Boost V2 Integration
    description: Integration endpoints for partners without knowledge of current Boost customers
  - name: Boost V1 Integration
    description: Legacy integration endpoints for partners familiar with existing Boost customers
  - name: Zapier Integration
    description: Webhook and integration endpoints for Zapier workflows
  - name: GraphQL
    description: GraphQL API endpoints

paths:
  /dashboard/integration/promo_campaign/{partner_short_code}:
    get:
      tags:
        - Boost V2 Integration
      operationId: createAgentPromo
      summary: Create Agent Promo Campaign
      description: Create a social media ad campaign to promote an agent's services
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
          description: Partner identifier assigned by Boost
        - name: first_name
          in: query
          required: true
          schema:
            type: string
          description: First name of the agent
        - name: last_name
          in: query
          required: true
          schema:
            type: string
          description: Last name of the agent
        - name: email
          in: query
          required: true
          schema:
            type: string
            format: email
          description: Email address of the agent
        - name: phone
          in: query
          schema:
            type: string
          description: Phone number of the agent
        - name: agent_img
          in: query
          schema:
            type: string
            format: uri
          description: URL to agent's photo for the ad
        - name: facebook_page_id
          in: query
          schema:
            type: string
          description: Facebook page ID (must be in HomeSpotter Business Manager)
        - name: headline
          in: query
          schema:
            type: string
          description: URL-encoded ad headline
        - name: title
          in: query
          schema:
            type: string
          description: URL-encoded ad title
        - name: description
          in: query
          schema:
            type: string
          description: URL-encoded ad description
        - name: broker_name
          in: query
          schema:
            type: string
          description: URL-encoded brokerage name
        - name: landing_page_url
          in: query
          schema:
            type: string
            format: uri
          description: URL for ad landing page
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: JWT authentication token
      responses:
        '200':
          description: Successfully created agent promo campaign
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Bad request - missing or invalid parameters
        '401':
          description: Unauthorized - invalid or expired token
        '403':
          description: Forbidden - insufficient permissions

  /dashboard/integration/leads_plus/{partner_short_code}:
    get:
      tags:
        - Boost V2 Integration
      operationId: accessLeadsPlus
      summary: Access Leads+ Dashboard
      description: Access the Leads+ subscription dashboard or purchase flow for an agent
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
          description: Partner identifier
        - name: first_name
          in: query
          required: true
          schema:
            type: string
        - name: last_name
          in: query
          required: true
          schema:
            type: string
        - name: email
          in: query
          required: true
          schema:
            type: string
            format: email
        - name: phone
          in: query
          schema:
            type: string
        - name: agent_img
          in: query
          schema:
            type: string
            format: uri
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully accessed Leads+ dashboard
          content:
            text/html:
              schema:
                type: string

  /dashboard/integration/campaign/{partner_short_code}:
    get:
      tags:
        - Boost V2 Integration
      operationId: createListingCampaign
      summary: Create Listing Campaign
      description: Create a campaign for a real estate listing with optional dynamic listing creation
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: mls_id
          in: query
          required: true
          schema:
            type: string
          description: MLS ID of the listing
        - name: zip
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d{5}(-\d{4})?$'
          description: ZIP code of the listing
        - name: address
          in: query
          schema:
            type: string
          description: Street address of the listing
        - name: city
          in: query
          schema:
            type: string
          description: City of the listing
        - name: state
          in: query
          schema:
            type: string
            maxLength: 2
          description: State code of the listing
        - name: country
          in: query
          schema:
            type: string
          description: Country of the listing
        - name: price
          in: query
          schema:
            type: number
            format: double
          description: Price of the listing
        - name: bed
          in: query
          schema:
            type: integer
            minimum: 0
          description: Number of bedrooms
        - name: bath
          in: query
          schema:
            type: number
            minimum: 0
          description: Number of bathrooms
        - name: sqft
          in: query
          schema:
            type: integer
            minimum: 0
          description: Square footage of the listing
        - name: desc
          in: query
          schema:
            type: string
          description: MLS description of the listing
        - name: latitude
          in: query
          schema:
            type: number
            format: double
            minimum: -90
            maximum: 90
          description: Latitude for geo-targeting
        - name: longitude
          in: query
          schema:
            type: number
            format: double
            minimum: -180
            maximum: 180
          description: Longitude for geo-targeting
        - name: status
          in: query
          schema:
            type: string
            enum:
              - new
              - rent
              - pending
              - sold
              - reducedprice
              - closed
          description: Status of the listing
        - name: first_name
          in: query
          schema:
            type: string
          description: Agent first name (for new agents)
        - name: last_name
          in: query
          schema:
            type: string
          description: Agent last name (for new agents)
        - name: phone
          in: query
          schema:
            type: string
          description: Agent phone (for new agents)
        - name: email
          in: query
          schema:
            type: string
            format: email
          description: Agent email (for new agents)
        - name: agent_img
          in: query
          schema:
            type: string
            format: uri
          description: Agent photo URL (for new agents)
        - name: banner_color
          in: query
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{6}$'
            default: '00a567'
          description: Hexadecimal color for status banner
        - name: broker_name
          in: query
          schema:
            type: string
            default: Boost By HomeSpotter
          description: Broker name for the ad
        - name: listing_url
          in: query
          schema:
            type: string
            format: uri
          description: URL where users land after clicking the ad
        - name: img_url
          in: query
          schema:
            type: string
            format: uri
          description: URL to featured property image
        - name: facebook_page_id
          in: query
          schema:
            type: string
          description: Facebook page ID for posting the ad
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Campaign created successfully
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized

  /dashboard/integration/dashboard/{partner_short_code}:
    get:
      tags:
        - Boost V2 Integration
      operationId: agentDashboard
      summary: Agent Dashboard/Boost Introduction
      description: Access agent's Boost dashboard or introduction page for new agents
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: first_name
          in: query
          required: true
          schema:
            type: string
        - name: last_name
          in: query
          required: true
          schema:
            type: string
        - name: email
          in: query
          required: true
          schema:
            type: string
            format: email
        - name: phone
          in: query
          schema:
            type: string
        - name: agent_img
          in: query
          schema:
            type: string
            format: uri
        - name: facebook_page_id
          in: query
          schema:
            type: string
        - name: headline
          in: query
          schema:
            type: string
        - name: title
          in: query
          schema:
            type: string
        - name: description
          in: query
          schema:
            type: string
        - name: broker_name
          in: query
          schema:
            type: string
        - name: landing_page_url
          in: query
          schema:
            type: string
            format: uri
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dashboard loaded successfully
          content:
            text/html:
              schema:
                type: string

  /dashboard/integration/update/{partner_short_code}:
    get:
      tags:
        - Boost V2 Integration
      operationId: updateListing
      summary: Update Listing
      description: Update listing information for an existing campaign
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: mls_id
          in: query
          required: true
          schema:
            type: string
          description: MLS ID of listing to update
        - name: zip
          in: query
          required: true
          schema:
            type: string
          description: ZIP code of listing
        - name: price
          in: query
          schema:
            type: number
            format: double
          description: Updated price
        - name: status
          in: query
          schema:
            type: string
            enum:
              - new
              - rent
              - pending
              - sold
              - reducedprice
              - closed
          description: Updated status
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Listing updated successfully
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized

  /dashboard/integration/dailystats/{partner_short_code}/{date}:
    get:
      tags:
        - Boost V2 Integration
      operationId: getDailyStats
      summary: Daily Stats Campaign Details
      description: Get statistics for campaigns running on a specific date
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: date
          in: path
          required: true
          schema:
            type: string
            format: date
          description: Date in yyyy-mm-dd format
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Daily stats retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyStatsResponse'

  /dashboard/integration/details/{partner_short_code}:
    get:
      tags:
        - Boost V2 Integration
      operationId: getCampaignDetails
      summary: Campaign Details
      description: Get detailed report of all campaigns for an agent
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Campaign details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailsResponse'

  /graphql:
    post:
      tags:
        - Boost V2 Integration
        - GraphQL
      operationId: checkAgentExists
      summary: Check if Agent Already Exists in Boost
      description: |
        Verify whether an agent has already been linked to a Boost account using GraphQL queries.
        This endpoint is part of Boost Integration V2 and uses a separate GraphQL API secret token
        (not the same as the JWT token used for other V2 endpoints).
        Use this to determine if an agent needs to be created or if they have an existing account.
      security:
        - graphql_token: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: GraphQL query
                variables:
                  type: object
                  description: Query variables
              example:
                query: |
                  query Agents($partnerShortCode: String, $partnerAgentId: ID!) {
                    agents(partnerShortCode: $partnerShortCode, partnerAgentId: $partnerAgentId, pagination: {first: 1}) {
                      totalCount
                      list {
                        firstName
                        lastName
                        emailAddress
                      }
                    }
                  }
                variables:
                  partnerShortCode: "YOUR_PARTNER_CODE"
                  partnerAgentId: "agent_12345"
      responses:
        '200':
          description: GraphQL query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentQueryResponse'
        '400':
          description: Invalid GraphQL query
        '401':
          description: Unauthorized - invalid token

  /zapier_webhook/subscribe:
    post:
      tags:
        - Zapier Integration
      operationId: subscribeWebhook
      summary: Subscribe to Webhook
      description: Creates a new webhook subscription for a Zapier workflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscription'
      responses:
        '200':
          description: Webhook subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request - missing or malformed parameters
        '401':
          description: Unauthorized - invalid API key

  /zapier_webhook/unsubscribe:
    delete:
      tags:
        - Zapier Integration
      operationId: unsubscribeWebhook
      summary: Unsubscribe from Webhook
      description: Removes an existing webhook subscription
      parameters:
        - name: api_key
          in: query
          required: true
          schema:
            type: string
          description: API key for authentication
      responses:
        '200':
          description: Webhook subscription removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized

  /zapier_webhook/sample_data:
    get:
      tags:
        - Zapier Integration
      operationId: getSampleData
      summary: Get Sample Data
      description: Returns sample data useful for Zap setup and testing
      parameters:
        - name: api_key
          in: query
          required: true
          schema:
            type: string
          description: API key for authentication
        - name: productId
          in: query
          required: true
          schema:
            type: string
          description: Product identifier
      responses:
        '200':
          description: Sample data retrieved successfully
          content:
            application/json:
              schema:
                type: object

  /dashboard/integration/all/{partner_short_code}:
    get:
      tags:
        - Boost V1 Integration
      operationId: getAllCampaignsV1
      summary: All Campaign Details
      description: Get report of all campaigns created via the integration, including rollup stats and individual campaign details. For partners familiar with existing Boost customers.
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: JWT token with customer_id, agent_id, and iat (V1 format)
      responses:
        '200':
          description: All campaigns retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailsResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized

  /dashboard/integration/campaign/{partner_short_code}/v1:
    get:
      tags:
        - Boost V1 Integration
      operationId: createListingCampaignV1
      summary: Create Listing Campaign
      description: Create a campaign for a real estate listing with optional dynamic listing creation. For partners familiar with existing Boost customers.
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: mls_id
          in: query
          required: true
          schema:
            type: string
        - name: zip
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d{5}(-\d{4})?$'
        - name: address
          in: query
          schema:
            type: string
        - name: city
          in: query
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
            maxLength: 2
        - name: country
          in: query
          schema:
            type: string
        - name: price
          in: query
          schema:
            type: number
            format: double
        - name: bed
          in: query
          schema:
            type: integer
            minimum: 0
        - name: bath
          in: query
          schema:
            type: number
            minimum: 0
        - name: sqft
          in: query
          schema:
            type: integer
            minimum: 0
        - name: desc
          in: query
          schema:
            type: string
        - name: latitude
          in: query
          schema:
            type: number
            format: double
            minimum: -90
            maximum: 90
        - name: longitude
          in: query
          schema:
            type: number
            format: double
            minimum: -180
            maximum: 180
        - name: status
          in: query
          schema:
            type: string
            enum:
              - new
              - rent
              - pending
              - sold
              - reducedprice
              - closed
        - name: first_name
          in: query
          schema:
            type: string
        - name: last_name
          in: query
          schema:
            type: string
        - name: phone
          in: query
          schema:
            type: string
        - name: email
          in: query
          schema:
            type: string
            format: email
        - name: agent_img
          in: query
          schema:
            type: string
            format: uri
        - name: banner_color
          in: query
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{6}$'
            default: '00a567'
        - name: broker_name
          in: query
          schema:
            type: string
            default: Boost By HomeSpotter
        - name: listing_url
          in: query
          schema:
            type: string
            format: uri
        - name: img_url
          in: query
          schema:
            type: string
            format: uri
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: JWT token with customer_id, agent_id, and iat (V1 format)
      responses:
        '200':
          description: Campaign created successfully
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized

  /dashboard/integration/dailystats/{partner_short_code}/{date}/v1:
    get:
      tags:
        - Boost V1 Integration
      operationId: getDailyStatsV1
      summary: Daily Stats Campaign Details
      description: Get statistics for campaigns running on a specific date. For partners familiar with existing Boost customers.
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: date
          in: path
          required: true
          schema:
            type: string
            format: date
          description: Date in yyyy-mm-dd format
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: JWT token with customer_id, agent_id, and iat (V1 format)
      responses:
        '200':
          description: Daily stats retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyStatsResponse'

  /dashboard/integration/details/{partner_short_code}/v1:
    get:
      tags:
        - Boost V1 Integration
      operationId: getCampaignDetailsV1
      summary: Campaign Details
      description: Get detailed report of all campaigns for an agent. For partners familiar with existing Boost customers.
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: JWT token with customer_id, agent_id, and iat (V1 format)
      responses:
        '200':
          description: Campaign details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailsResponse'

  /dashboard/integration/update/{partner_short_code}/v1:
    get:
      tags:
        - Boost V1 Integration
      operationId: updateListingV1
      summary: Update Listing
      description: Update listing information for an existing campaign. For partners familiar with existing Boost customers.
      parameters:
        - name: partner_short_code
          in: path
          required: true
          schema:
            type: string
        - name: mls_id
          in: query
          required: true
          schema:
            type: string
        - name: zip
          in: query
          required: true
          schema:
            type: string
        - name: price
          in: query
          schema:
            type: number
            format: double
        - name: status
          in: query
          schema:
            type: string
            enum:
              - new
              - rent
              - pending
              - sold
              - reducedprice
              - closed
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: JWT token with customer_id, agent_id, and iat (V1 format)
      responses:
        '200':
          description: Listing updated successfully
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized

  /zapier_webhook/me:
    get:
      tags:
        - Zapier Integration
      operationId: validateApiKey
      summary: Validate API Key
      description: Validates the provided API key and returns account-related info
      parameters:
        - name: api_key
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: API key is valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountInfo'
        '401':
          description: Invalid API key

components:
  securitySchemes:
    jwt_token:
      type: apiKey
      in: query
      name: token
      description: |
        JWT token for Boost V2 Integration containing:
        - partner_agent_id: unique partner agent identifier (< 100 characters)
        - iss: partner identifier (partner short code)
        - aud: always "boost.homespotter.com"
        - iat: issued at timestamp (numeric seconds from epoch)
        Token expires after 24 hours and cannot be set in the future.
    jwt_token_v1:
      type: apiKey
      in: query
      name: token
      description: |
        JWT token for Boost V1 Integration (DEPRECATED) containing:
        - customer_id: unique customer identifier (default: 1169)
        - agent_id: unique agent identifier in vendor's system
        - iat: issued at timestamp (numeric seconds from epoch)
        Token expires after 24 hours.
    graphql_token:
      type: http
      scheme: bearer
      description: GraphQL API secret token provided by Boost team (different from JWT token)
    api_key:
      type: apiKey
      in: query
      name: api_key
      description: API key for Zapier webhook endpoints

  schemas:
    CampaignStats:
      type: object
      properties:
        created_time_utc:
          type: string
          format: date-time
        start_time_utc:
          type: string
          format: date-time
        end_time_utc:
          type: string
          format: date-time
        campaign_id:
          type: string
        type:
          type: string
          enum:
            - AgentPromo
            - Listing
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        agent_name:
          type: string
        status:
          type: string
          enum:
            - Running
            - Ended
            - Paused
        total_impressions:
          type: integer
        total_clicks:
          type: integer
        total_engagements:
          type: integer
        web_impressions:
          type: integer
        web_clicks:
          type: integer
        social_impressions:
          type: integer
        social_clicks:
          type: integer

    DailyStatsResponse:
      type: object
      properties:
        date:
          type: string
          format: date
        stats:
          type: array
          items:
            $ref: '#/components/schemas/CampaignStats'
        rows:
          type: integer

    CampaignDetail:
      type: object
      properties:
        campaign_id:
          type: string
        type:
          type: string
          enum:
            - Listing
            - AgentPromo
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        headline:
          type: string
        title:
          type: string
        description:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        price:
          type: number
          format: double
        agent_first_name:
          type: string
        agent_last_name:
          type: string
        impressions:
          type: integer
        clicks:
          type: integer
        campaign_status:
          type: string
          enum:
            - Enabled
            - Disabled

    CampaignDetailsResponse:
      type: object
      properties:
        rollupStats:
          type: object
          properties:
            total_clicks:
              type: integer
            total_impressions:
              type: integer
            total_campaigns:
              type: integer
            running_campaigns:
              type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/CampaignDetail'
        rows:
          type: integer

    AgentInfo:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        emailAddress:
          type: string
          format: email

    AgentQueryResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            agents:
              type: object
              properties:
                totalCount:
                  type: integer
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/AgentInfo'

    WebhookSubscription:
      type: object
      required:
        - hook_url
        - product_id
        - api_key
      properties:
        hook_url:
          type: string
          format: uri
          description: Zapier webhook URL
        product_id:
          type: string
          description: Product identifier
        api_key:
          type: string
          description: API key for authentication

    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
            - error
        message:
          type: string

    AccountInfo:
      type: object
      properties:
        account_id:
          type: string
        account_name:
          type: string
        email:
          type: string
          format: email
        api_key_status:
          type: string
          enum:
            - active
            - inactive

x-authentication:
  overview: "All Boost Integration endpoints use JWT-based authentication passed as a URL query parameter named 'token'"
  shared_requirements:
    - Tokens expire after 24 hours
    - Tokens cannot be set in the future
    - Format is numeric value representing seconds from Unix epoch
    - Sign tokens with shared_secret_key provided by Boost
  v2_authentication:
    use_case: "For partners WITHOUT knowledge of current Boost customers"
    jwt_payload:
      partner_agent_id:
        type: string
        description: Unique partner agent identifier (< 100 characters)
        example: "123456789"
      iss:
        type: string
        description: Issuer - partner identifier assigned by Boost
        example: "PARTNER_SHORT_CODE"
      aud:
        type: string
        description: Audience - always this value
        example: "boost.homespotter.com"
      iat:
        type: integer
        description: Issued at timestamp (seconds from epoch)
        example: 1566918809
    php_example: |
      $token = JWT::encode(
        [
          'partner_agent_id' => 123456789,
          'iss' => 'PARTNER_SHORT_CODE',
          'aud' => 'boost.homespotter.com',
          'iat' => time()
        ],
        "shared_secret_key"
      );
      $url .= "&token=$token";
    behavior: "When an agent completes a purchase, HomeSpotter creates an agent record tied to partner_agent_id. Subsequent visits with same partner_agent_id logs into existing HS agent record."
  v1_authentication:
    use_case: "For partners familiar with existing Boost customers"
    jwt_payload:
      customer_id:
        type: integer
        description: Unique customer ID known by partner and HomeSpotter
        default: 1169
        example: 1169
      agent_id:
        type: string
        description: Unique alphanumeric user ID in third party vendor's system
        example: "46576"
      iat:
        type: integer
        description: Issued at timestamp (seconds from epoch)
        example: 1566918809
    php_example: |
      $token = JWT::encode(
        [
          'customer_id' => 1169,
          'agent_id' => '46576',
          'iat' => time()
        ],
        "shared_secret_key"
      );
      $url .= "&token=$token";
  graphql_authentication:
    use_case: "For checking if an agent exists in Boost (V2 only)"
    type: "Bearer token (different from JWT)"
    token_name: "graphql_api_secret_token"
    header: "Authorization: Bearer [graphql_api_secret_token]"
    note: "This token is provided separately by the Boost team and is NOT the same as the JWT token."
  testing_and_debugging:
    - Use https://jwt.io/ to create and test JWT tokens
    - Example V2 payload at https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    - Tokens must be URL-encoded when passed as query parameters

x-api-lifecycle:
  integration_versions:
    v1:
      target_partners: 'Partners familiar with existing Boost customers'
      authentication: 'JWT with customer_id, agent_id, iat'
    v2:
      target_partners: 'Partners without knowledge of current Boost customers'
      authentication: 'JWT with partner_agent_id, iss (partner code), aud, iat'

x-internal-notes:
  authentication:
    - JWT tokens expire after 24 hours
    - Cannot be set in the future
    - Use https://jwt.io/ for token creation and testing
    - GraphQL API uses separate graphql_api_secret_token (different from JWT)
  domains:
    Boost V2 Integration:
      - Production: https://boost.homespotter.com
      - QA/Staging: Available upon request from Boost team
      - All dashboard integration endpoints use this domain
    GraphQL Endpoint:
      - Production: https://api.homespotter.com/graphql
      - Used for: Checking if agent exists in Boost
      - Requires: graphql_api_secret_token (provided by Boost team)
  v2_endpoints:
    - Promo Campaign Creation
    - Leads+ Access
    - Listing Campaign Creation
    - Agent Dashboard/Boost Introduction
    - Update Listing
    - Daily Stats
    - Campaign Details
    - Check if Agent Exists (GraphQL)
  rate_limits: 'To be determined with Boost team'