Authentication

All API requests must include a valid JWT Bearer token obtained through Auth0. The same Auth0 tenant is used as the main BootOG platform.

Auth0 Configuration

Sending the Token

Include the Bearer token in the Authorization header on every request:

POST /api/v1/assignments/import
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Obtaining a Token (Client Credentials)

curl -X POST \
  https://dev-p4p31vijvpe6x78q.us.auth0.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":     "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience":      "YOUR_API_AUDIENCE",
    "grant_type":    "client_credentials"
  }'

Quick Start

Get your first inspection assignment imported in under 5 minutes.

curl "/api/v1/assignments/status?policyNumber=POL-2024-00123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Postman Collection

The quickest way to explore and test the API is with our official Postman collection. It includes pre-configured requests for both endpoints, example bodies, and environment variables for your token.

▶ Run in Postman

Manual Setup — Environment Variables

Pre-Request Script (Auto Token Refresh)

Add this to your collection's Pre-request Script tab to automatically fetch and cache tokens:

const tokenExpiry = pm.environment.get('token_expiry');
const now = new Date().getTime();

if (!tokenExpiry || now > parseInt(tokenExpiry)) {
  pm.sendRequest({
    url: `https://${pm.environment.get('auth0_domain')}/oauth/token`,
    method: 'POST',
    header: { 'Content-Type': 'application/json' },
    body: {
      mode: 'raw',
      raw: JSON.stringify({
        client_id:     pm.environment.get('client_id'),
        client_secret: pm.environment.get('client_secret'),
        audience:      pm.environment.get('audience'),
        grant_type:    'client_credentials'
      })
    }
  }, (err, res) => {
    const { access_token, expires_in } = res.json();
    pm.environment.set('access_token', access_token);
    pm.environment.set('token_expiry', now + (expires_in * 1000));
  });
}

Errors & Status Codes

The API uses standard HTTP status codes. Both endpoints return plain HTTP status codes — check the code to determine the outcome. No structured error body is returned on failure.

Import Assignments

Submit one or more underwriter inspection assignments for asynchronous processing. Assignments are queued immediately and processed in the background.

Check Assignment Status

Query the current processing status of a previously imported inspection assignment using its policy number.

Recommended Polling Strategy

Since import is asynchronous, implement exponential back-off polling rather than tight loops:

async function pollStatus(policyNumber, maxAttempts = 10) {
  let delay = 2000; // start at 2 s
  for (let i = 0; i < maxAttempts; i++) {
    await new Promise(r => setTimeout(r, delay));
    const res = await fetch(
      `/api/v1/assignments/status?policyNumber=${policyNumber}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    if (res.status === 200) return res.json();
    if (res.status !== 404) throw new Error(`Unexpected ${res.status}`);
    delay = Math.min(delay * 1.5, 30000); // cap at 30 s
  }
  throw new Error('Assignment not ready after max retries');
}

Schemas

Full field reference for all request and response models used by the Inspection Assignments API.

ImportAssignmentsRequest

InspectionRequest

AgentRequest

PolicyHolderRequest

MailingRequest

LocationRequest

StatusResponse

🔒 Security Best Practices

Follow these guidelines to ensure a secure and reliable integration with the API.

To ensure secure integration:

• Store your client_secret securely (never expose in frontend code)
• Use HTTPS for all requests
• Cache tokens and avoid unnecessary token requests
• Rotate credentials periodically if required

⏱ Token Expiry

Tokens are valid for a limited time (e.g., 24 hours). You should refresh the token before it expires.

🚫 Common Mistakes to Avoid

• Requesting a new token for every API call
• Exposing credentials in client-side applications
• Hardcoding tokens without refresh logic

📊 Rate Limiting & Monitoring