Developer Reference
API Documentation
Build integrations with the NearbyAssist platform. RESTful endpoints, consistent JSON responses, and comprehensive coverage for bookings, messaging, billing, and more.
Base URL
https://api.nearbyassist.comAuthentication
Bearer token via Authorization header
Rate Limits
500 req/15 min (global), 20 req/15 min (auth endpoints)
Format
JSON request/response. UTF-8 encoding. ISO 8601 dates.
Authentication
All authenticated endpoints require a Bearer token in the Authorization header. Obtain a token by signing in via POST /api/auth/signin. For partner integrations, use an API key with the X-API-Key header instead.
# Session token (user authentication)
curl https://api.nearbyassist.com/api/users/profile \
-H "Authorization: Bearer <access_token>"
# API key (partner integration)
curl https://api.nearbyassist.com/api/integrations/partner/bookings \
-H "X-API-Key: na_live_..."
Get Your API Key
Generate API keys from the Integrations dashboard. Keys use the na_live_ prefix and support scoped permissions (bookings:read, bookings:write, etc.). The full key is shown only once at creation.
Authentication
(3 endpoints)Users
(3 endpoints)Businesses
(7 endpoints)Bookings
(8 endpoints)Services
(4 endpoints)Reviews & Q&A
(6 endpoints)Messaging
(5 endpoints)Billing & Payments
(6 endpoints)Staff
(5 endpoints)Integrations
(7 endpoints)Webhooks
(3 endpoints)Error Responses
All errors return a JSON body with error and optional errors array for validation failures.
{
"error": "Validation failed",
"errors": [
{ "field": "email", "message": "Email is required" },
{ "field": "password", "message": "Minimum 8 characters" }
]
}| Code | Status | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 201 | Created | Resource created successfully. |
| 400 | Bad Request | Invalid request body or query parameters. |
| 401 | Unauthorized | Missing or invalid authentication token. |
| 403 | Forbidden | Authenticated but lacking permission for this resource. |
| 404 | Not Found | Resource does not exist. |
| 409 | Conflict | Resource conflict (e.g. duplicate booking slot). |
| 422 | Unprocessable Entity | Validation failed. Check the errors array in the response. |
| 429 | Too Many Requests | Rate limit exceeded. Retry after the Retry-After header value. |
| 500 | Internal Server Error | Unexpected error. Contact support if persistent. |
Pagination
List endpoints support cursor-based pagination using page and limit query parameters. Default limit is 20, max is 100.
GET /api/bookings/my-bookings?page=2&limit=10
{
"bookings": [...],
"total": 47,
"page": 2,
"limit": 10
}Webhook Events
Register webhook endpoints to receive real-time notifications. All payloads include a X-NearbyAssist-Signature header for verification using HMAC-SHA256.
booking.createdA new booking is confirmed.booking.updatedBooking status or time changed.booking.cancelledA booking was cancelled.lead.receivedNew lead available for your business.lead.acceptedA lead was accepted and charged.review.createdNew review posted for your business.message.receivedInbound message from any channel.payment.completedA payment was processed successfully.// Verify webhook signature
const crypto = require('crypto');
const signature = req.headers['x-nearbyassist-signature'];
const expected = crypto
.createHmac('sha256', webhookSecret)
.update(JSON.stringify(req.body))
.digest('hex');
if (signature !== expected) {
return res.status(401).json({ error: 'Invalid signature' });
}Integration Guide
Step-by-step walkthrough for OAuth, API keys, and common integration scenarios.
OpenAPI Spec
Download the OpenAPI 3.0 YAML spec. Import into Swagger UI or code generators.
Postman Collection
Pre-configured Postman collection with all endpoints ready to test.
Need help integrating?
Our developer support team is available to help with integration questions, debugging, and best practices.