AutoLeadStar Shoppers API

openapi: 3.2.0
info:
  title: Autoleadstar Shoppers API
  version: 1.0.0
  contact:
    name: API Support
    email: support@fullpath.com
  termsOfService: https://www.fullpath.com/legal-and-trust/
  description: 'Operations tagged shoppers across 2 of this provider''s published API definitions: autoleadstar-fullpath-api-openapi.yml, autoleadstar-mcp-tools-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://fullpath.com/api/v2/external/consent-management
  description: Production (fullpath.com)
- url: https://api.fullpath.com/v1
  description: Production (api.fullpath.com)
- url: https://staging-api.fullpath.com/v1
  description: Staging (api.fullpath.com)
tags:
- name: shoppers
  description: Operations related to shoppers
paths:
  /dealerships/{dealershipId}/shoppers:
    servers:
    - url: https://fullpath.com/api/v2/external/consent-management
      description: Production (fullpath.com)
    - url: https://api.fullpath.com/v1
      description: Production (api.fullpath.com)
    - url: https://staging-api.fullpath.com/v1
      description: Staging (api.fullpath.com)
    get:
      security:
      - Bearer: []
      tags:
      - shoppers
      summary: List shoppers
      description: 'Returns a paginated list of shoppers. Supports exact matching via the `q` query parameter for email or phone.


        Additional fields can be included in the response using the `embed` parameter. Available embed options:

        - `primary_contact` - Primary contact information (first_name, last_name, email, phone numbers, address)

        - `latest_lead_date` - Date of the latest lead (YYYY-MM-DD)

        - `latest_sale_date` - Date of the latest sale (YYYY-MM-DD)

        - `latest_sale` - Latest sale information

        - `latest_lead` - Latest lead information including vehicle details

        - `adf_leads` - Array of ADF leads

        - `latest_marketing_touchpoint_date` - Date of the latest marketing touchpoint (YYYY-MM-DD)

        - `marketing_engagement_score` - Marketing engagement score

        - `loyalty_score` - Loyalty score


        Multiple embed options can be specified as a comma-separated list, e.g., `embed=primary_contact,latest_lead_date,latest_lead`.

        '
      operationId: listShoppers
      parameters:
      - $ref: '#/components/parameters/DealershipId'
      - in: query
        name: q
        description: Exact match query for email address or phone number (E.164 format)
        schema:
          type: string
        required: false
      - in: query
        name: embed
        description: 'Comma-separated list of fields to embed in the response. Available options:

          primary_contact, latest_lead_date, latest_sale_date, latest_sale, latest_lead, adf_leads, latest_marketing_touchpoint_date, marketing_engagement_score, loyalty_score

          '
        schema:
          type: string
        required: false
        example: primary_contact,latest_lead_date
      - in: query
        name: page
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
        required: false
      - in: query
        name: per_page
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        required: false
      - in: query
        name: sort
        description: Sort order (comma-separated field names with optional - prefix for descending, e.g., `-created_at`)
        schema:
          type: string
        required: false
      responses:
        '200':
          description: A paginated list of shoppers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShoppersResponse'
        '204':
          description: No shoppers found
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /dealerships/{dealershipId}/shoppers/{id}:
    servers:
    - url: https://fullpath.com/api/v2/external/consent-management
      description: Production (fullpath.com)
    - url: https://api.fullpath.com/v1
      description: Production (api.fullpath.com)
    - url: https://staging-api.fullpath.com/v1
      description: Staging (api.fullpath.com)
    get:
      security:
      - Bearer: []
      tags:
      - shoppers
      summary: Get a single shopper
      description: 'Retrieves a shopper by `id`.


        Additional fields can be included in the response using the `embed` parameter. This endpoint supports all embed options available for the list endpoint, plus additional options only available for single shopper requests.


        **Embed options available for both list and single shopper:**

        - `primary_contact` - Primary contact information (extended version with more fields in single shopper response)

        - `latest_lead_date` - Date of the latest lead (YYYY-MM-DD)

        - `latest_sale_date` - Date of the latest sale (YYYY-MM-DD)

        - `latest_sale` - Latest sale information

        - `latest_lead` - Latest lead information including vehicle details

        - `adf_leads` - Array of ADF leads

        - `latest_marketing_touchpoint_date` - Date of the latest marketing touchpoint (YYYY-MM-DD)

        - `marketing_engagement_score` - Marketing engagement score

        - `loyalty_score` - Loyalty score


        **Additional embed options available only for single shopper:**

        - `contacts` - Array of all contacts associated with the shopper

        - `location` - Location information (city, state, zipcode, etc.)

        - `score` - Shopper score

        - `public_link` - Public link for the shopper

        - `customer_lifetime_value` - Customer lifetime value information (sales, services, total)

        - `latest_sale_estimated_equity` - Estimated equity from latest sale

        - `household_flag` - Whether this is a household shopper

        - `customer_tags` - Array of customer tags

        - `is_enriched` - Whether the shopper data has been enriched

        - `salesperson` - Assigned salesperson

        - `group_shopper_id` - Group shopper identifier

        - `financial_durability_index` - Financial durability index

        - `aim_propensity_score` - AIM propensity score


        Multiple embed options can be specified as a comma-separated list, e.g., `embed=primary_contact,contacts,location,customer_lifetime_value`.

        '
      operationId: getShopperById
      parameters:
      - $ref: '#/components/parameters/DealershipId'
      - in: path
        name: id
        required: true
        description: Shopper identifier (integer)
        schema:
          type: integer
      - in: query
        name: embed
        description: 'Comma-separated list of fields to embed in the response.


          Available for both list and single: primary_contact, latest_lead_date, latest_sale_date, latest_sale, latest_lead, adf_leads, latest_marketing_touchpoint_date, marketing_engagement_score, loyalty_score


          Available only for single shopper: contacts, location, score, public_link, customer_lifetime_value, latest_sale_estimated_equity, household_flag, customer_tags, is_enriched, salesperson, group_shopper_id, financial_durability_index, aim_propensity_score

          '
        schema:
          type: string
        required: false
        example: primary_contact,contacts,location,customer_lifetime_value
      responses:
        '200':
          description: Shopper found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shopper'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Shopper not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /dealerships/{dealershipId}/shoppers/{id}/audiences:
    servers:
    - url: https://fullpath.com/api/v2/external/consent-management
      description: Production (fullpath.com)
    - url: https://api.fullpath.com/v1
      description: Production (api.fullpath.com)
    - url: https://staging-api.fullpath.com/v1
      description: Staging (api.fullpath.com)
    get:
      security:
      - Bearer: []
      tags:
      - shoppers
      summary: List audiences for a shopper
      description: Returns a paginated list of audiences associated with the shopper
      operationId: listShopperAudiences
      parameters:
      - $ref: '#/components/parameters/DealershipId'
      - in: path
        name: id
        required: true
        description: Shopper identifier (integer)
        schema:
          type: integer
      - in: query
        name: page
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
        required: false
      - in: query
        name: per_page
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        required: false
      - in: query
        name: sort
        description: Sort order (comma-separated field names with optional - prefix for descending)
        schema:
          type: string
        required: false
      responses:
        '200':
          description: A paginated list of audiences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudiencesResponse'
        '204':
          description: No audiences found
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Shopper not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /dealerships/{dealershipId}/shoppers/{id}/events:
    servers:
    - url: https://fullpath.com/api/v2/external/consent-management
      description: Production (fullpath.com)
    - url: https://api.fullpath.com/v1
      description: Production (api.fullpath.com)
    - url: https://staging-api.fullpath.com/v1
      description: Staging (api.fullpath.com)
    get:
      security:
      - Bearer: []
      tags:
      - shoppers
      summary: List events for a shopper
      description: 'Returns a paginated list of events associated with the shopper. Events are returned ungrouped in a flat array.


        Supported event types:

        - `page_view` - Website page view events

        - `lead` - Lead events from CRM

        - `sale` - Sale events from CRM

        - `conversion` - Conversion events (e.g., form submissions)

        - `input_tracking` - Input tracking events

        - `ad_click` - Ad click events

        - `enrichment` - Data enrichment events

        - `lead_handling_sms_sent` - Lead handling SMS sent events

        - `email_click` - Email click events

        - `email_open` - Email open events

        - `email_sent` - Email sent events

        - `sms_click` - SMS click events

        - `sms_replied` - SMS replied events

        - `sms_sent` - SMS sent events

        - `appointment` - Appointment events

        - `service_lead` - Service lead events from CRM

        - `service_ro` - Service repair order events from CRM

        - `service_appointment` - Service appointment events

        '
      operationId: listShopperEvents
      parameters:
      - $ref: '#/components/parameters/DealershipId'
      - in: path
        name: id
        required: true
        description: Shopper identifier (integer)
        schema:
          type: integer
      - in: query
        name: page
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
        required: false
      - in: query
        name: per_page
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        required: false
      - in: query
        name: sort
        description: Sort order (comma-separated field names with optional - prefix for descending)
        schema:
          type: string
        required: false
      responses:
        '200':
          description: A paginated list of events
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShopperEvent'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '204':
          description: No events found
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Shopper not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /dealerships/{dealershipId}/shoppers/{id}/emails:
    servers:
    - url: https://fullpath.com/api/v2/external/consent-management
      description: Production (fullpath.com)
    - url: https://api.fullpath.com/v1
      description: Production (api.fullpath.com)
    - url: https://staging-api.fullpath.com/v1
      description: Staging (api.fullpath.com)
    get:
      security:
      - Bearer: []
      tags:
      - shoppers
      summary: List emails for a shopper
      description: Returns a paginated list of email addresses associated with the shopper
      operationId: listShopperEmails
      parameters:
      - $ref: '#/components/parameters/DealershipId'
      - in: path
        name: id
        required: true
        description: Shopper identifier (integer)
        schema:
          type: integer
      - in: query
        name: page
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
        required: false
      - in: query
        name: per_page
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        required: false
      - in: query
        name: sort
        description: Sort order (comma-separated field names with optional - prefix for descending)
        schema:
          type: string
        required: false
      responses:
        '200':
          description: A paginated list of email addresses
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShopperEmail'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '204':
          description: No emails found
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Shopper not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /dealerships/{dealershipId}/shoppers/{id}/phones:
    servers:
    - url: https://fullpath.com/api/v2/external/consent-management
      description: Production (fullpath.com)
    - url: https://api.fullpath.com/v1
      description: Production (api.fullpath.com)
    - url: https://staging-api.fullpath.com/v1
      description: Staging (api.fullpath.com)
    get:
      security:
      - Bearer: []
      tags:
      - shoppers
      summary: List phones for a shopper
      description: Returns a paginated list of phone numbers associated with the shopper
      operationId: listShopperPhones
      parameters:
      - $ref: '#/components/parameters/DealershipId'
      - in: path
        name: id
        required: true
        description: Shopper identifier (integer)
        schema:
          type: integer
      - in: query
        name: page
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
        required: false
      - in: query
        name: per_page
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        required: false
      - in: query
        name: sort
        description: Sort order (comma-separated field names with optional - prefix for descending)
        schema:
          type: string
        required: false
      responses:
        '200':
          description: A paginated list of phone numbers
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShopperPhone'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '204':
          description: No phones found
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Shopper not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /dealerships/{dealershipId}/audiences/{id}/shoppers:
    servers:
    - url: https://fullpath.com/api/v2/external/consent-management
      description: Production (fullpath.com)
    - url: https://api.fullpath.com/v1
      description: Production (api.fullpath.com)
    - url: https://staging-api.fullpath.com/v1
      description: Staging (api.fullpath.com)
    get:
      security:
      - Bearer: []
      tags:
      - shoppers
      summary: List shoppers in an audience
      description: Returns a paginated list of shoppers belonging to the given audience
      operationId: listAudienceShoppers
      parameters:
      - $ref: '#/components/parameters/DealershipId'
      - in: path
        name: id
        required: true
        description: Audience identifier (integer)
        schema:
          type: integer
      - in: query
        name: page
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
        required: false
      - in: query
        name: per_page
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        required: false
      - in: query
        name: sort
        description: Sort order (comma-separated field names with optional - prefix for descending)
        schema:
          type: string
        required: false
      responses:
        '200':
          description: Paginated shoppers in the audience
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceShoppersResponse'
        '204':
          description: No shoppers found
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Audience not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AppointmentEvent:
      type: object
      required:
      - identifier
      - type
      - timestamp
      properties:
        identifier:
          type: string
          description: Unique identifier for the event
          example: '1234567890'
        type:
          type: string
          enum:
          - appointment
          example: appointment
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the event occurred
          example: '2024-01-15T10:30:00Z'
        product:
          type:
          - string
          - 'null'
          description: Product identifier
          example: crm
        crm_lead_id:
          type:
          - string
          - 'null'
          description: CRM lead identifier
          example: '1234567890'
        crm_customer:
          type:
          - string
          - 'null'
          description: CRM customer identifier
          example: '9876543210'
        vehicle_canonical_details:
          type:
          - object
          - 'null'
          description: Vehicle canonical details
          example: null
        is_confirmed:
          type:
          - boolean
          - 'null'
          description: Whether the appointment is confirmed
          example: false
        is_shown:
          type:
          - boolean
          - 'null'
          description: Whether the appointment was shown
          example: true
        results:
          type:
          - string
          - 'null'
          description: Appointment results
          example: null
        salesperson:
          type:
          - string
          - 'null'
          description: Assigned salesperson
          example: null
      description: Appointment event
    EnrichmentEvent:
      type: object
      required:
      - identifier
      - type
      - timestamp
      properties:
        identifier:
          type: string
          description: Unique identifier for the event
          example: '100365000312'
        type:
          type: string
          enum:
          - enrichment
          example: enrichment
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the event occurred
          example: '2024-01-15T10:30:00Z'
        product:
          type:
          - string
          - 'null'
          description: Product identifier
          example: enrichment
        first_name:
          type:
          - string
          - 'null'
          description: First name
          example: John
        last_name:
          type:
          - string
          - 'null'
          description: Last name
          example: Doe
        verified:
          type:
          - object
          - 'null'
          properties:
            emails:
              type: array
              items:
                type: string
              example: []
            phones:
              type: array
              items:
                type: string
              example:
              - '5551234567'
            vehicles:
              type: array
              items:
                type: object
              example: []
          description: Verified data
          example: null
        enriched:
          type:
          - object
          - 'null'
          properties:
            emails:
              type: array
              items:
                type: string
              example:
              - john.doe@example.com
            phones:
              type: array
              items:
                type: string
              example:
              - '5551234568'
            vehicles:
              type: array
              items:
                type: object
                properties:
                  model:
                    type: string
                    example: CAMRY
                  year:
                    type: string
                    example: '2020'
                  make:
                    type: string
                    example: TOYOTA
                  vin:
                    type: string
                    example: 1HGBH41JXMN109186
            address:
              type:
              - object
              - 'null'
              properties:
                address:
                  type: string
                  example: 123 Main St
                city:
                  type: string
                  example: Anytown
                state:
                  type: string
                  example: NY
                zipcode:
                  type: string
                  example: '12345'
          description: Enriched data
          example: null
        match_status:
          type:
          - string
          - 'null'
          description: Match status
          example: Active
      description: Enrichment event
    PrimaryContact:
      type:
      - object
      - 'null'
      properties:
        source:
          type:
          - string
          - 'null'
          description: Source of the contact (e.g., customer, crm_customer)
          example: customer
        first_name:
          type:
          - string
          - 'null'
          description: First name
          example: John
        middle_name:
          type:
          - string
          - 'null'
          description: Middle name
          example: null
        last_name:
          type:
          - string
          - 'null'
          description: Last name
          example: Doe
        full_name:
          type:
          - string
          - 'null'
          description: Full name
          example: John Doe
        main_email_addresses:
          type:
          - string
          - 'null'
          format: email
          description: Main email address
          example: john.doe@example.com
        alternative_email_addresses:
          type:
          - string
          - 'null'
          description: Alternative email addresses
          example: null
        cell_phone:
          type:
          - string
          - 'null'
          description: Cell phone number
          example: '+15555551234'
        home_phone:
          type:
          - string
          - 'null'
          description: Home phone number
          example: '+15555551235'
        work_phone:
          type:
          - string
          - 'null'
          description: Work phone number
          example: null
        address:
          type:
          - string
          - 'null'
          description: Street address
          example: null
        city:
          type:
          - string
          - 'null'
          description: City
          example: Anytown
        state:
          type:
          - string
          - 'null'
          description: State
          example: NY
        zipcode:
          type:
          - string
          - 'null'
          description: ZIP code
          example: '12345'
        timestamp:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the contact was created/updated
          example: '2024-01-15T10:30:00Z'
        latitude:
          type:
          - number
          - 'null'
          description: Latitude coordinate
          example: null
        longitude:
          type:
          - number
          - 'null'
          description: Longitude coordinate
          example: null
        status:
          type:
          - string
          - 'null'
          description: Contact status
          example: null
        crm_link:
          type:
          - string
          - 'null'
          format: uri
          description: Link to CRM customer dashboard
          example: null
        creation_date:
          type:
          - string
          - 'null'
          format: date
          description: Creation date (YYYY-MM-DD)
          example: null
        external_customer_id:
          type:
          - string
          - 'null'
          description: External customer identifier
          example: null
        customer_type:
          type:
          - string
          - 'null'
          description: Customer type
          example: null
        email:
          type:
          - string
          - 'null'
          format: email
          description: Email address (legacy field, use main_email_addresses)
          example: john.doe@example.com
        full_address:
          type:
          - string
          - 'null'
          description: Full address (legacy field, use city, state, zipcode)
          example: Anytown, NY, 12345
      description: Primary contact information for a shopper. Extended version available in single shopper responses.
    Location:
      type:
      - object
      - 'null'
      properties:
        title:
          type:
          - string
          - 'null'
          description: Full location title
          example: Anytown, NY, 12345
        city:
          type:
          - string
          - 'null'
          description: City
          example: Anytown
        state:
          type:
          - string
          - 'null'
          description: State
          example: NY
        zipcode:
          type:
          - string
          - 'null'
          description: ZIP code
          example: '12345'
        source:
          type:
          - string
          - 'null'
          description: Source of the location data
          example: customer
        address:
          type:
          - string
          - 'null'
          description: Street address
          example: null
        distance_from_dealership:
          type:
          - number
          - 'null'
          description: Distance from dealership (in miles or kilometers)
          example: null
      description: Location information for a shopper
    Vehicle:
      type:
      - object
      - 'null'
      properties:
        vin:
          type:
          - string
          - 'null'
          description: Vehicle Identification Number
          example: 1HGBH41JXMN109186
        condition:
          type:
          - string
          - 'null'
          description: Vehicle condition (e.g., new, used)
          example: new
        year:
          type:
          - string
          - 'null'
          description: Vehicle year
          example: '2024'
        make:
          type:
          - string
          - 'null'
          description: Vehicle make
          example: Toyota
        model:
          type:
          - string
          - 'null'
          description: Vehicle model
          example: Camry
        trim:
          type:
          - string
          - 'null'
          description: Vehicle trim
          example: LE
      description: Vehicle information
    PageViewEvent:
      type: object
      required:
    

# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/autoleadstar/refs/heads/main/openapi/autoleadstar-shoppers-api-openapi.yml