openapi: 3.0.3
info:
  title: Badger Maps Accounts 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: Accounts
  description: Accounts (customers) - the businesses and contacts a rep maps and visits.
paths:
  /customers/:
    get:
      operationId: listAccounts
      tags:
      - Accounts
      summary: List accounts
      description: Returns an array of accounts (customers) owned by the authenticated user. The optional `rn` parameter (modeled) scopes the list to a managed user.
      parameters:
      - name: rn
        in: query
        required: false
        description: Optional managed-user id to scope the list to (modeled).
        schema:
          type: integer
      responses:
        '200':
          description: A list of accounts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAccount
      tags:
      - Accounts
      summary: Create an account
      description: Creates a new account (customer). Requires at least a name and address plus an account owner; latitude/longitude and custom data fields are optional.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountInput'
      responses:
        '201':
          description: The created account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{account_id}/:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getAccount
      tags:
      - Accounts
      summary: Retrieve an account
      description: Returns a single account with its locations and custom fields.
      responses:
        '200':
          description: The requested account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateAccount
      tags:
      - Accounts
      summary: Update an account
      description: Partially updates an account - for example custom_text fields or a change of account_owner.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountInput'
      responses:
        '200':
          description: The updated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAccount
      tags:
      - Accounts
      summary: Delete an account
      description: Deletes an account (customer). Returns 204 No Content on success.
      responses:
        '204':
          description: The account was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Account:
      type: object
      properties:
        id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: string
        account_owner:
          type: integer
          description: User id of the account owner.
        external_id:
          type: string
          description: Identifier of the account in an external system (e.g. CRM).
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        custom_text:
          type: object
          description: Custom text data fields configured on the account.
          additionalProperties: true
    AccountInput:
      type: object
      required:
      - last_name
      - address
      - account_owner
      properties:
        last_name:
          type: string
        first_name:
          type: string
        address:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: string
        account_owner:
          type: integer
        lat:
          type: number
          format: float
        lng:
          type: number
          format: float
        custom_text:
          type: object
          additionalProperties: true
    Location:
      type: object
      properties:
        id:
          type: integer
        address:
          type: string
        lat:
          type: number
          format: float
        lng:
          type: number
          format: float
    Error:
      type: object
      properties:
        detail:
          type: string
        status:
          type: integer
  responses:
    Unauthorized:
      description: Authentication is missing or the token is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      description: The account (customer) id.
      schema:
        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.'