Getting started

Overview

The Banner API is a REST interface for reading and writing data, including properties, projects, cost items, contracts, invoices, and payments.

All endpoints are HTTPS-based, return UTF-8 JSON, and require a bearer token for authentication.

🟢 Live status: status.withbanner.com · 📧 Support: [email protected]

Every Banner integration follows the same three-step flow:

  1. Receive your integration ID. Contact your Banner Customer Success Manager to request an integration ID.
  2. Exchange it for a bearer token. Call GET /api/integration/getToken?id=<id> to receive a token valid for 30 days.
  3. Call the API. Include the token on every subsequent request as Authorization: Bearer <token>.

Base URLs

Environment Base URL Purpose
Production https://withbanner.com Live customer data
Sandbox (Beta Blue) https://beta-blue.withbanner.com Non-production testing

Quick start

# 1. Exchange your integration ID for a bearer token
TOKEN=$(curl -s "<https://withbanner.com/api/integration/getToken?id=YOUR_INTEGRATION_ID>" \
  | jq -r '.token')

# 2. Call an endpoint with the token
curl "<https://withbanner.com/api/v2/integration/getShells>" \
  -H "Authorization: Bearer $TOKEN"

Authentication

GET Token

Banner uses bearer tokens for authentication — user passwords and session cookies are not supported. Exchange your Banner-issued id for a bearer token valid for 30 days, then include that token on every request. Call this endpoint once, cache the token, and reuse it for all subsequent calls until it nears expiry (re-exchange your id to refresh).

Endpoint

Environment URL
Production https://withbanner.com/api/integration/getToken
Sandbox https://beta-blue.withbanner.com/api/integration/getToken

Query parameters

Name Type Required Description
id string Yes The integration ID provided to you by Banner.

Response

Returns a bearer token string valid for 30 days. Include it in the Authorization header of every subsequent request, prefixed with Bearer . Tokens are scoped to a single Banner account/instance and cannot be shared across environments.

Example request

curl "<https://withbanner.com/api/integration/getToken?id=YOUR_INTEGRATION_ID>"

Example response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use the token

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Conventions