BildOut API

The BildOut API uses OAuth 2.0 with the Authorization Code flow. This ensures users explicitly grant access to their data.

Scopes

OAuth Flow

// Using fetch to exchange authorization code
const response = await fetch('https://bildout.com/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: authCode,
    redirect_uri: 'https://yourapp.com/callback',
    client_id: process.env.BILDOUT_CLIENT_ID,
    client_secret: process.env.BILDOUT_CLIENT_SECRET,
  }),
});

const { access_token, refresh_token, expires_in } = await response.json();

API requests are rate limited per access token:

• Standard: 100 requests per minute
• Burst: 20 requests per second

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1703980800

Payments represent money received from customers (incoming) or paid to vendors (outgoing).

Endpoints

• GET /api/v1/payments - List payments
• GET /api/v1/payments/:id - Get payment details

Customers are the people or businesses you invoice for your work.

Endpoints

• GET /api/v1/customers - List customers
• POST /api/v1/customers - Create customer
• GET /api/v1/customers/:id - Get customer
• PUT /api/v1/customers/:id - Update customer
• DELETE /api/v1/customers/:id - Delete customer

Projects represent construction jobs. Link invoices and payments to projects for detailed financial tracking.

Endpoints

• GET /api/v1/projects - List projects
• POST /api/v1/projects - Create project
• GET /api/v1/projects/:id - Get project
• PUT /api/v1/projects/:id - Update project
• DELETE /api/v1/projects/:id - Delete project
• GET /api/v1/projects/:id/financials - Get financial summary

Vendors are suppliers, subcontractors, and consultants you pay for materials and services.

Endpoints

• GET /api/v1/vendors - List vendors
• POST /api/v1/vendors - Create vendor
• GET /api/v1/vendors/:id - Get vendor
• PUT /api/v1/vendors/:id - Update vendor
• DELETE /api/v1/vendors/:id - Delete vendor

Webhooks notify your application in real-time when events occur in BildOut. Subscribe to specific events to keep your systems in sync.

Event Types

Verifying Signatures

All webhook payloads are signed with HMAC-SHA256. Always verify signatures before processing webhooks.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signatureHeader: string,
  secret: string
): boolean {
  // Parse header: t=timestamp,v1=signature
  const parts = signatureHeader.split(',');
  const timestamp = parts.find(p => p.startsWith('t='))?.slice(2);
  const signature = parts.find(p => p.startsWith('v1='))?.slice(3);

  if (!timestamp || !signature) return false;

  // Check timestamp is recent (within 5 minutes)
  const age = Math.abs(Date.now() / 1000 - parseInt(timestamp));
  if (age > 300) return false;

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

The API uses standard HTTP status codes and returns JSON error responses:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ],
    "request_id": "req_abc123xyz"
  }
}

Error Codes