API & Developers

The Developers section provides tools for integrating Plotwise with your other systems through our API.

Accessing Developer Settings

1. Click organization name (top left)
2. Select "Organization settings"
3. Click "Developers" tab

API Keys

API keys authenticate your applications when calling the Plotwise API.

Creating an API Key

1. Click "Create API Key"
2. Enter a descriptive name
3. Select permissions
4. Click "Create"
5. Copy the key immediately (shown only once)

API Key Permissions

Managing API Keys

View existing keys:

• Key name
• Last used date
• Permissions
• Created date

Revoke a key:

1. Find key in list
2. Click "Revoke"
3. Confirm
4. Key immediately invalidated

API Key Best Practices

• Use descriptive names (e.g., "CRM Integration - Production")
• Create separate keys for different applications
• Use minimum required permissions
• Rotate keys periodically
• Revoke unused keys

API Usage

Authentication

Include your API key in requests:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.plotwise.us/v1/permits

Rate Limits

API requests are rate limited:

• Starter: 100 requests/minute
• Professional: 1,000 requests/minute
• Enterprise: Custom limits

Usage Tracking

View API usage metrics:

• Requests per day/week/month
• Errors and failures
• Top endpoints called

Webhooks

Webhooks notify your systems when events occur in Plotwise.

Creating a Webhook

1. Click "Add Webhook"
2. Enter endpoint URL (HTTPS required)
3. Select events to subscribe
4. Add secret for verification (optional)
5. Save

Webhook Events

Webhook Payload

Example payload:

{
  "event": "permit.status_changed",
  "timestamp": "2026-01-23T10:45:00Z",
  "organization_id": "org_xxx",
  "data": {
    "permit_uuid": "abc-123",
    "permit_number": "BLD-26-0521670",
    "previous_status": "Pending",
    "new_status": "In Review"
  }
}

Webhook Security

Verify webhooks using the secret:

1. Add secret when creating webhook
2. Plotwise includes signature header
3. Verify signature in your endpoint
4. Reject invalid signatures

Testing Webhooks

1. Create webhook pointing to test endpoint
2. Click "Send Test Event"
3. Verify your endpoint receives it
4. Check payload structure

Webhook Failures

If your endpoint fails:

• Retried up to 5 times
• Exponential backoff
• Notification after repeated failures
• Can manually retry from logs

API Documentation

Full API Reference

Complete API documentation available at:

• api.plotwise.us/docs
• OpenAPI/Swagger specification
• Code examples

Common Endpoints

SDKs and Libraries

Official libraries available for:

• JavaScript/TypeScript
• Python
• (More coming soon)

Integration Examples

CRM Integration

Sync permit contacts to your CRM:

1. Create API key with Read permission
2. Call /v1/contacts endpoint
3. Map fields to your CRM
4. Schedule periodic sync

Webhook to Slack

Send notifications to Slack:

1. Create webhook endpoint (your server)
2. Subscribe to relevant events
3. Forward to Slack webhook
4. Format as Slack message

Automated Reporting

Build custom reports:

1. Create API key
2. Query permits endpoint
3. Aggregate data
4. Generate report

Troubleshooting

Related Documentation

• Organization Settings Overview
• API Documentation
• Billing & Subscription