List a rep's optimized routes and retrieve a single route with its ordered waypoints - each waypoint references an account location, its position in the sequence, and timing details. Routes are the optimized driving plans Badger generates across a set of accounts.
openapi: 3.0.3
info:
title: Badger Maps 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.
- name: Accounts
description: Accounts (customers) - the businesses and contacts a rep maps and visits.
- name: Locations
description: Physical, geocoded locations attached to an account.
- name: Check-Ins
description: Timestamped activity logs recorded against an account (the /appointments/ resource).
- name: Routes
description: Optimized driving routes and their ordered waypoints.
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'
/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'
/locations/{location_id}/:
parameters:
- $ref: '#/components/parameters/LocationId'
patch:
operationId: updateLocation
tags:
- Locations
summary: Update an account location
description: >-
Updates a location attached to an account. An address is required;
latitude/longitude may be supplied to override Badger's geocoding.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LocationInput'
responses:
'200':
description: The updated location.
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/appointments/:
get:
operationId: listCheckIns
tags:
- Check-Ins
summary: List check-ins
description: >-
Returns the check-ins recorded against an account. Filter by account
with the `customer_id` query parameter.
parameters:
- name: customer_id
in: query
required: false
description: The account (customer) id to return check-ins for.
schema:
type: integer
responses:
'200':
description: A list of check-ins.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CheckIn'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCheckIn
tags:
- Check-Ins
summary: Create a check-in
description: >-
Records a new check-in against an account. Requires the account
(customer) id; a type and free-text comments are optional.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckInInput'
responses:
'201':
description: The created check-in.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckIn'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/routes/:
get:
operationId: listRoutes
tags:
- Routes
summary: List routes
description: Returns the authenticated user's routes (id, name, and route date).
responses:
'200':
description: A list of routes.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RouteSummary'
'401':
$ref: '#/components/responses/Unauthorized'
/routes/{route_id}/:
parameters:
- $ref: '#/components/parameters/RouteId'
get:
operationId: getRoute
tags:
- Routes
summary: Retrieve a route
description: >-
Returns a single route with its ordered waypoints. Each waypoint
references an account location, its position in the sequence, and timing
details.
responses:
'200':
description: The requested route.
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
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.
parameters:
AccountId:
name: account_id
in: path
required: true
description: The account (customer) id.
schema:
type: integer
LocationId:
name: location_id
in: path
required: true
description: The location id.
schema:
type: integer
RouteId:
name: route_id
in: path
required: true
description: The route id.
schema:
type: integer
responses:
Unauthorized:
description: Authentication is missing or the token is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
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'
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
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
LocationInput:
type: object
required:
- address
properties:
address:
type: string
lat:
type: number
format: float
lng:
type: number
format: float
CheckIn:
type: object
description: A check-in log against an account (served under /appointments/).
properties:
id:
type: integer
customer:
type: integer
description: The account (customer) id the check-in belongs to.
type:
type: string
description: Check-in type.
comments:
type: string
log_datetime:
type: string
format: date-time
created_by:
type: integer
description: User id of the check-in author.
CheckInInput:
type: object
required:
- customer
properties:
customer:
type: integer
description: The account (customer) id to log the check-in against.
type:
type: string
comments:
type: string
RouteSummary:
type: object
properties:
id:
type: integer
name:
type: string
route_date:
type: string
format: date
Route:
allOf:
- $ref: '#/components/schemas/RouteSummary'
- type: object
properties:
waypoints:
type: array
items:
$ref: '#/components/schemas/Waypoint'
Waypoint:
type: object
properties:
position:
type: integer
description: Order of this stop in the route.
customer_id:
type: integer
location:
$ref: '#/components/schemas/Location'
start_time:
type: string
description: Planned arrival/timing detail (modeled).
duration:
type: integer
description: Planned stop duration in minutes (modeled).
Error:
type: object
properties:
detail:
type: string
status:
type: integer