API Reference

Complete documentation for the Signals REST API

Quick Start

API Access - Pro & Enterprise Plans Only

REST API access is available exclusively on Pro ($499/mo) and Enterprise plans. Starter and Growth plans do not include API access. View pricing plans →

Base URL

https://api.signals.com/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

Authorization
Bearer YOUR_API_KEY

Get your API key from Account Settings → API Keys

Rate Limits

10,000
requests/day
Pro Plan ($499/mo)
Unlimited
custom limits
Enterprise Plan

API access is not available on Starter or Growth plans. Compare plans

GET

/events

Retrieve building events (permits, inspections, violations, complaints) with optional filters.

Query Parameters

ParameterTypeDescription
citystringFilter by city (e.g., "NYC", "MIAMI")
event_typestringFilter by type: "permit", "violation", "inspection", "complaint"
statusstringFilter by status (e.g., "issued", "pending", "approved")
days_backintegerNumber of days to look back (default: 7, max: 90)
searchstringFull-text search across title and description
limitintegerNumber of results per page (default: 50, max: 500)
offsetintegerPagination offset (default: 0)

Example Request

curl -X GET \
"https://api.signals.com/v1/events?city=NYC&event_type=permit&days_back=7" \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "total": 1245,
  "limit": 50,
  "offset": 0,
  "events": [
    {
      "id": 12345,
      "source": "dob_permit_dobnow",
      "external_id": "JOB123456",
      "title": "New Building - 10 stories",
      "url": "https://a810-bisweb.nyc.gov/bisweb/JobsQueryByNumberServlet?passjobnumber=123456",
      "city": "NYC",
      "event_type": "permit",
      "status": "issued",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "raw": {
        "address": "123 Main St, Manhattan",
        "work_type": "NB",
        "filing_date": "2025-01-15"
      }
    }
  ]
}
GET

/stats

Retrieve aggregated statistics about building events across cities.

Example Request

curl -X GET \
"https://api.signals.com/v1/stats" \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "total_events": 245678,
  "last_updated": "2025-01-15T10:30:00Z",
  "by_city": {
    "NYC": 89234,
    "MIAMI": 23456,
    "HOUSTON": 18765
  },
  "by_type": {
    "permit": 123456,
    "violation": 67890,
    "inspection": 34567,
    "complaint": 19765
  }
}
GET

/export.csv

Export filtered events to CSV format. Accepts the same query parameters as /events.

Example Request

curl -X GET \
"https://api.signals.com/v1/export.csv?city=NYC&event_type=permit" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o events.csv

Webhooks

Webhooks allow you to receive real-time notifications when new events match your criteria. Available on Professional and Enterprise plans.

Webhook Payload

When an event matches your webhook rules, we'll send a POST request to your configured URL:

{
  "event": "event.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": 12345,
    "source": "dob_permit_dobnow",
    "external_id": "JOB123456",
    "title": "New Building - 10 stories",
    "city": "NYC",
    "event_type": "permit",
    "status": "issued"
  }
}

Configure webhooks in your Dashboard → Integrations

Error Codes

CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Contact support

SDK Libraries

Official SDK libraries coming soon for popular languages:

🐍
Python
Coming Soon
📘
TypeScript
Coming Soon
☕
Java
Coming Soon
🦀
Rust
Coming Soon

Ready to start building?

Get your API key and start integrating Signals data today

API access requires a Pro ($499/mo) or Enterprise plan

View PricingContact Sales