REST APIBase URL: api.vespine.io/v1

Vespine API

The Vespine API provides programmatic access to utility bills, parsed data, and account management. Build custom integrations, automate workflows, and sync utility data with your systems.

RESTful

Standard REST endpoints with JSON responses

Secure

TLS 1.3 encryption, API key authentication

Real-time

Webhooks for instant notifications

Authentication

Authenticate API requests using a Bearer token in the Authorization header. API keys are available in your dashboard under Settings → API Keys.

Authorization Header

Authorization: Bearer sk_live_your_api_key_here

Keep your API keys secure

Never expose API keys in client-side code or public repositories.

Quick Start

Get up and running in minutes. Here are the most common API operations.

1List all accounts

GET/accounts

bash

curl https://api.vespine.io/v1/accounts \
  -H "Authorization: Bearer sk_live_..."

2Get statements for an account

GET/accounts/:id/statements

bash

curl https://api.vespine.io/v1/accounts/acct_xyz/statements \
  -H "Authorization: Bearer sk_live_..."

3Download a statement PDF

GET/statements/:id/download

bash

curl https://api.vespine.io/v1/statements/stmt_abc/download \
  -H "Authorization: Bearer sk_live_..." \
  -o statement.pdf

Accounts

Accounts represent connected utility provider credentials. Each account can have multiple statements.

Account Object

Accountjson

{
  "id": "acct_xyz789",
  "provider": "pge",
  "provider_name": "Pacific Gas & Electric",
  "account_number": "1234567890",
  "service_address": "123 Main St, San Francisco, CA 94102",
  "status": "active",
  "last_sync": "2025-01-15T14:32:00Z",
  "created_at": "2024-06-01T10:00:00Z"
}

Endpoints

GET/accountsList all connected utility accounts

GET/accounts/{id}Retrieve a specific account

POST/accountsConnect a new utility account

DELETE/accounts/{id}Disconnect an account

GET/accounts/{id}/statementsList statements for an account

Statements

Statements contain parsed utility bill data including amounts, usage, dates, and the original PDF.

Statement Object

Statementjson

{
  "id": "stmt_abc123",
  "account_id": "acct_xyz789",
  "provider": "pge",
  "statement_date": "2025-01-15",
  "due_date": "2025-02-05",
  "amount_due": 284.73,
  "previous_balance": 0.00,
  "currency": "USD",
  "usage": {
    "value": 892,
    "unit": "kWh",
    "billing_days": 31
  },
  "service_address": "123 Main St, San Francisco, CA 94102",
  "billing_period": {
    "start": "2024-12-15",
    "end": "2025-01-14"
  },
  "charges": [
    { "description": "Electric Usage", "amount": 178.40 },
    { "description": "Delivery Charges", "amount": 92.33 },
    { "description": "Taxes & Fees", "amount": 14.00 }
  ],
  "pdf_url": "/v1/statements/stmt_abc123/download",
  "parsed_at": "2025-01-15T14:32:00Z"
}

Endpoints

GET/statements/{id}Retrieve statement with parsed data

GET/statements/{id}/downloadDownload original PDF

Webhooks

Receive real-time notifications when events occur. Webhooks are sent as POST requests with a JSON payload.

Events

statement.created

A new statement has been fetched and parsed

statement.updated

Statement data has been updated or corrected

account.connected

A new account was successfully connected

account.disconnected

An account was disconnected

account.error

An error occurred with account sync

job.completed

A sync job finished successfully

job.failed

A sync job failed

Webhook Payload

statement.createdjson

{
  "id": "evt_123abc",
  "type": "statement.created",
  "created": "2025-01-15T14:32:00Z",
  "data": {
    "object": {
      "id": "stmt_abc123",
      "account_id": "acct_xyz789",
      "provider": "pge",
      "amount_due": 284.73,
      "due_date": "2025-02-05",
      "pdf_url": "/v1/statements/stmt_abc123/download"
    }
  }
}

Webhook Signatures

All webhooks include an X-Vespine-Signature header. Always verify signatures before processing.

Error Handling

The API uses standard HTTP status codes. Errors include a JSON body with details.

Code	Description
`200`	Success
`400`	Bad request — invalid parameters
`401`	Unauthorized — invalid or missing API key
`404`	Not found — resource doesn't exist
`429`	Rate limited — too many requests
`500`	Server error — something went wrong

Error Responsejson

{
  "error": {
    "type": "invalid_request_error",
    "code": "account_not_found",
    "message": "No account found with ID 'acct_invalid'",
    "param": "account_id"
  }
}

Rate Limits

Rate limits vary by plan. The API returns rate limit headers with every response.

Growth

100 req/min

Scale

500 req/min

Enterprise

Custom

Rate Limit Headers

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

Ready to get started?

Get API access and start building your integration.

Get API Access View Plans