v1

Naybourhood API

Programmatic access to the Naybourhood buyer intelligence platform. Manage leads, score buyers, track developments, configure webhooks, and pull analytics.

Interactive API Reference

Try endpoints directly in your browser with Swagger UI

Open Reference

Base URL

https://app.naybourhood.ai/api/v1

Authentication

All API requests require a Bearer token. Create API keys in your dashboard under Settings → API Keys.

bash
curl -X POST https://app.naybourhood.ai/api/v1/score \
  -H "Authorization: Bearer nb_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"lead": {"full_name": "John Smith", "email": "john@example.com"}}'

API keys are shown once at creation. Store them securely. Never expose keys in client-side code.

Rate Limits

Default: 60 requests/minute per API key. Rate limit info is returned in response headers. Each API key has granular permissions: leads_read, leads_write, developments_read, webhooks_manage, stats_read.

Response Headers

X-RateLimit-Remaining: 58X-Response-Time: 45ms

429 Too Many Requests

{"error": "Rate limit exceeded..."}

Leads

GET/api/v1/leads
leads_read

List leads for your company. Supports pagination, filtering by classification/status, and search by name or email.

Response

json
{
  "data": [
    {
      "id": "uuid",
      "full_name": "Sarah Chen",
      "email": "sarah@example.com",
      "classification": "Qualified",
      "quality_score": 65,
      "intent_score": 55,
      "status": "Viewing Booked",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}

* Query params: page, per_page, classification, status, search.

POST/api/v1/leads
leads_write

Create a new lead and automatically score them using the AI engine.

Request Body

json
{
  "full_name": "Sarah Chen",
  "email": "sarah@example.com",
  "phone": "+44 7700 900000",
  "budget": "500000",
  "payment_method": "mortgage",
  "timeline": "3 months",
  "purpose": "primary residence",
  "location": "London",
  "bedrooms": 2
}

Response

json
{
  "id": "uuid",
  "full_name": "Sarah Chen",
  "email": "sarah@example.com",
  "classification": "Qualified",
  "quality_score": 55,
  "intent_score": 45,
  "confidence_score": 75,
  "status": "Contact Pending",
  "created_at": "2026-03-22T10:00:00Z"
}
GET/api/v1/leads/:id
leads_read

Retrieve a single lead with full score breakdown.

Response

json
{
  "id": "uuid",
  "full_name": "Sarah Chen",
  "email": "sarah@example.com",
  "classification": "Qualified",
  "quality_score": 55,
  "intent_score": 45,
  "confidence_score": 75,
  "score_breakdown": { ... },
  "status": "Viewing Booked",
  "created_at": "2026-03-01T12:00:00Z"
}
PATCH/api/v1/leads/:id
leads_write

Update a lead. If financial fields change (budget, payment_method, timeline), the lead is automatically re-scored.

Request Body

json
{
  "budget": "750000",
  "timeline": "immediate",
  "status": "Reserved"
}

Response

json
{
  "id": "uuid",
  "full_name": "Sarah Chen",
  "budget": "750000",
  "classification": "Hot Lead",
  "quality_score": 72,
  "intent_score": 80,
  "status": "Reserved"
}

* Only include fields you want to change.

* Financial field changes trigger automatic re-scoring.

DELETE/api/v1/leads/:id
leads_write

Soft-delete a lead by setting its status to Archived. The lead data is retained.

Response

json
{
  "message": "Lead archived successfully"
}
GET/api/v1/leads/:id/scores
leads_read

Retrieve the score history for a lead, showing how their scores have changed over time.

Response

json
{
  "data": [
    {
      "id": "uuid",
      "quality_score": 72,
      "intent_score": 80,
      "confidence_score": 85,
      "classification": "Hot Lead",
      "scored_at": "2026-03-22T10:00:00Z",
      "scored_by": "api"
    },
    {
      "id": "uuid",
      "quality_score": 55,
      "intent_score": 45,
      "confidence_score": 75,
      "classification": "Qualified",
      "scored_at": "2026-03-01T12:00:00Z",
      "scored_by": "api"
    }
  ]
}

Scoring

POST/api/v1/score
score_single

Score a single lead using the Naybourhood AI scoring engine. Pass either a buyer_id to score an existing lead, or inline lead data.

Request Body

json
{
  "lead": {
    "full_name": "Sarah Chen",
    "email": "sarah@example.com",
    "phone": "+44 7700 900000",
    "budget": "500000",
    "payment_method": "mortgage",
    "timeline": "3 months",
    "purpose": "primary residence",
    "location": "London",
    "bedrooms": 2
  }
}

Response

json
{
  "quality_score": 55,
  "intent_score": 45,
  "confidence_score": 75,
  "classification": "Nurture",
  "call_priority": 4,
  "call_priority_reason": "Nurture Lead - Scheduled Follow-up",
  "response_time": "Within 48 hours",
  "is_28_day_buyer": false,
  "is_fake_lead": false,
  "risk_flags": ["Mortgage not yet approved"],
  "score_breakdown": { ... }
}

* Alternatively pass {"buyer_id": "uuid"} to score an existing lead in your account.

* Classification values: Hot Lead, Qualified, Needs Qualification, Nurture, Low Priority, Disqualified.

POST/api/v1/score/batch
score_batch

Score up to 50 leads in a single request. Pass either an array of buyer_ids or inline lead objects.

Request Body

json
{
  "leads": [
    {
      "full_name": "Lead One",
      "email": "one@example.com",
      "budget": "750000",
      "payment_method": "cash",
      "timeline": "immediate"
    },
    {
      "full_name": "Lead Two",
      "email": "two@example.com",
      "budget": "300000",
      "timeline": "6 months"
    }
  ]
}

Response

json
{
  "total": 2,
  "scored": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "quality_score": 40,
      "intent_score": 50,
      "confidence_score": 50,
      "classification": "Needs Qualification",
      "call_priority": 3,
      "is_28_day_buyer": true,
      "is_fake_lead": false,
      "risk_flags": []
    },
    ...
  ]
}

* Maximum 50 leads per batch request.

* Alternatively pass {"buyer_ids": ["uuid1", "uuid2"]} to score existing leads.

Developments

GET/api/v1/developments
developments_read

List all developments for your company.

Response

json
{
  "data": [
    {
      "id": "uuid",
      "name": "Riverside Quarter",
      "location": "London SE1",
      "status": "Active",
      "total_units": 120,
      "created_at": "2026-01-15T09:00:00Z"
    }
  ]
}
GET/api/v1/developments/:id
developments_read

Get development details with aggregated lead statistics including total leads, breakdown by classification, and average scores.

Response

json
{
  "id": "uuid",
  "name": "Riverside Quarter",
  "location": "London SE1",
  "status": "Active",
  "total_units": 120,
  "lead_stats": {
    "total_leads": 84,
    "by_classification": {
      "Hot Lead": 12,
      "Qualified": 28,
      "Nurture": 30,
      "Low Priority": 14
    },
    "avg_quality_score": 52,
    "avg_intent_score": 48
  }
}

Webhooks

POST/api/v1/webhook/lead-created
webhook

Ingest a new lead from your CRM or forms. The lead is created, auto-scored, and optionally pushed to HubSpot.

Request Body

json
{
  "full_name": "James Wilson",
  "email": "james@buyer.com",
  "phone": "+44 7700 900001",
  "budget": "1200000",
  "payment_method": "cash",
  "timeline": "28 days",
  "source": "Rightmove"
}

Response

json
{
  "success": true,
  "buyer_id": "uuid-of-new-lead",
  "scoring": {
    "quality_score": 40,
    "intent_score": 50,
    "confidence_score": 70,
    "classification": "Hot Lead",
    "call_priority": 1,
    "is_28_day_buyer": true,
    "is_fake_lead": false
  }
}
GET/api/v1/webhooks
webhooks_manage

List your outbound webhook subscriptions.

Response

json
{
  "data": [
    {
      "id": "uuid",
      "url": "https://your-app.com/webhook",
      "events": ["lead.created", "lead.scored"],
      "is_active": true,
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}
POST/api/v1/webhooks
webhooks_manage

Register a webhook URL to receive events. A signing secret is auto-generated for HMAC-SHA256 verification.

Request Body

json
{
  "url": "https://your-app.com/webhook",
  "events": ["lead.created", "lead.scored", "lead.status_changed"]
}

Response

json
{
  "id": "uuid",
  "url": "https://your-app.com/webhook",
  "events": ["lead.created", "lead.scored", "lead.status_changed"],
  "secret": "whsec_...",
  "is_active": true,
  "created_at": "2026-03-22T10:00:00Z"
}

* The secret is returned once at creation. Store it to verify webhook signatures.

* Outbound deliveries include X-Webhook-Signature (sha256=hex), X-Webhook-Event, and X-Webhook-Timestamp headers.

* Failed deliveries are retried up to 3 times with exponential backoff.

DELETE/api/v1/webhooks/:id
webhooks_manage

Remove a webhook subscription. Events will no longer be delivered to this URL.

Response

json
{
  "message": "Webhook deleted"
}

Stats

GET/api/v1/stats
stats_read

Get aggregated lead statistics for your company: totals, classification/status breakdown, average scores, and 7/30-day trends.

Response

json
{
  "total_leads": 342,
  "by_classification": {
    "Hot Lead": 28,
    "Qualified": 95,
    "Nurture": 120,
    "Low Priority": 65,
    "Disqualified": 34
  },
  "by_status": {
    "Contact Pending": 80,
    "Viewing Booked": 45,
    "Reserved": 22,
    "Sold": 18
  },
  "avg_quality_score": 52,
  "avg_intent_score": 48,
  "leads_last_7d": 23,
  "leads_last_30d": 87
}

Error Codes

StatusMeaningAction
400
Bad RequestCheck request body format
401
UnauthorizedCheck API key is valid and active
403
ForbiddenAPI key lacks required permission
404
Not FoundBuyer ID does not exist or not in your company
429
Rate LimitedWait and retry. Default: 60 req/min
500
Server ErrorRetry with exponential backoff

Scoring Classifications

Hot Lead

28-day buyer OR quality/intent >= 70

Qualified

Quality >= 60, intent >= 50

Needs Qualification

Confidence < 50, missing data

Nurture

Good quality but low intent

Low Priority

Quality < 40 or flagged low urgency

Disqualified

Fake lead or data mismatch

SDK Generation

Generate a typed client from the OpenAPI spec using openapi-generator-cli.

bash
# TypeScript
npx @openapitools/openapi-generator-cli generate \
  -i https://naybourhood.ai/api/v1/openapi.json \
  -g typescript-fetch \
  -o ./naybourhood-sdk

# Python
npx @openapitools/openapi-generator-cli generate \
  -i https://naybourhood.ai/api/v1/openapi.json \
  -g python \
  -o ./naybourhood-sdk-python

Naybourhood API v1

Questions? Contact support@naybourhood.ai