openapi: 3.0.3
info:
  title: Badger Maps Accounts Users API
  description: 'REST API for Badger Maps, field sales route-planning and CRM software. The API lets teams programmatically manage accounts (customers), account locations, optimized routes, check-ins (served under the /appointments/ resource), and users. Base URL: https://badgerapis.badgermapping.com/api/2. All requests are authenticated with a token supplied in an `Authorization: Token <api_key>` header. API/Developer Key access is included with paid plans (max 25k requests per day, per team); the key must be enabled by contacting Badger Maps support (support@badgermapping.com).

    Endpoint paths, methods, and the core request/response fields below are grounded in Badger Maps'' published API Blueprint (Apiary). Fields marked "modeled" in descriptions are reasonable inferences where the public docs are thin and require an enabled key to verify exhaustively.'
  version: '2.0'
  contact:
    name: Badger Maps Support
    url: https://support.badgermapping.com
    email: support@badgermapping.com
servers:
- url: https://badgerapis.badgermapping.com/api/2
  description: Badger Maps API v2
security:
- tokenAuth: []
tags:
- name: Users
  description: Authentication, the authenticated user profile, and user search.
paths:
  /login/:
    post:
      operationId: login
      tags:
      - Users
      summary: Authenticate and obtain an API token
      description: 'Exchanges a username and password for an API token that is then sent in the `Authorization: Token <api_key>` header on subsequent requests.'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - username
              - password
              properties:
                username:
                  type: string
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: Authentication succeeded; returns the token and user id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /profiles/:
    get:
      operationId: getProfile
      tags:
      - Users
      summary: Retrieve the authenticated user profile
      description: Returns the profile of the authenticated user, including company info, profile settings, and the account custom data-field schema (datafields).
      responses:
        '200':
          description: The authenticated user's profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /search/users/:
    get:
      operationId: searchUsers
      tags:
      - Users
      summary: Search for users
      description: Searches users the authenticated account manages, by email or user ID.
      parameters:
      - name: q
        in: query
        required: true
        description: Query string - an email address or user ID.
        schema:
          type: string
      responses:
        '200':
          description: Matching users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication is missing or the token is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    AuthResponse:
      type: object
      properties:
        token:
          type: string
          description: API token to send in the Authorization header.
        status:
          type: string
        user_id:
          type: integer
    Profile:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        company:
          type: object
          description: Company the user belongs to.
          additionalProperties: true
        datafields:
          type: array
          description: Custom data-field schema configured for accounts.
          items:
            type: object
            additionalProperties: true
        settings:
          type: object
          description: Profile settings (modeled).
          additionalProperties: true
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        first_name:
          type: string
        email:
          type: string
          format: email
    Error:
      type: object
      properties:
        detail:
          type: string
        status:
          type: integer
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Token authentication. Send `Authorization: Token <api_key>`. Contact Badger Maps support to have your API/Developer Key enabled.'