Badger Maps Accounts API

openapi: 3.2.0
info:
  title: Badger Maps Accounts API
  description: REST API for Badger Maps, field sales route-planning and CRM software.
  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:
    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
    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
    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
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      description: The account (customer) id.
      schema:
        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'
  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.'