Skip to main content
GET
/
me
curl https://app.neariq.io/api/v1/me \
  -H "X-NearIQ-Key: niq_your_key_here"
Returns your business profile — rating, review count, category, address, and linked Google Place ID.
​
X-NearIQ-Key
string
required
Your API key from Settings > API Keys
curl https://app.neariq.io/api/v1/me \
  -H "X-NearIQ-Key: niq_your_key_here"

{
  "id": "biz_abc123",
  "name": "Joe's Pizza",
  "address": "123 Main St, New York, NY 10001",
  "rating": 4.6,
  "reviewCount": 312,
  "category": "Pizza restaurant",
  "googlePlaceId": "ChIJ...",
  "website": "https://joespizza.com",
  "phone": "+12125551234"
}

​
GET /me/snapshots

Daily rating and review count history for trend analysis. 
curl "https://app.neariq.io/api/v1/me/snapshots?limit=30" \
  -H "X-NearIQ-Key: niq_your_key_here"
Query parameters
ParameterTypeDefaultDescription
limitinteger90Number of most-recent snapshots (max 365)
fromISO date-Inclusive start date filter
toISO date-Inclusive end date filter. Date-only values include the full day.
{
  "snapshots": [
    { "checkedAt": "2026-04-27T06:00:00Z", "rating": 4.6, "reviewCount": 312 },
    { "checkedAt": "2026-04-26T06:00:00Z", "rating": 4.6, "reviewCount": 310 }
  ]
}

​
GET /me/reviews

Paginated list of your Google reviews. 
curl "https://app.neariq.io/api/v1/me/reviews?limit=20&sort=newest" \
  -H "X-NearIQ-Key: niq_your_key_here"
Query parameters
ParameterTypeDefaultDescription
limitinteger50Reviews to return (max 200)
sortstringnewestnewest, oldest, highest, or lowest
Review text is refreshed when available. If text is being refreshed, text is null and reviewTextStatus is loading; rating, author, date, and other metadata remain available. 
{
  "reviews": [
    {
      "rating": 5,
      "text": null,
      "author": "A Google user",
      "publishedAt": "2026-04-18T06:00:00Z",
      "ownerResponse": null,
      "reviewTextStatus": "loading"
    }
  ]
}

​
GET /me/gbp-health

Your Google Business Profile health score and breakdown. 
curl https://app.neariq.io/api/v1/me/gbp-health \
  -H "X-NearIQ-Key: niq_your_key_here"

{
  "score": 84,
  "maxScore": 100,
  "checks": [
    { "key": "photos", "label": "Photos on listing", "done": true, "points": 20 }
  ]
}

​
DELETE /api/businesses/me/delete

Soft-deletes your active business. Data is preserved for 30 days — you can restore it during the grace period. After 30 days, a background job permanently removes the business and all associated data. Only the business owner or organization owner can delete. 
curl -X DELETE "https://app.neariq.io/api/businesses/me/delete"
Run this from an authenticated dashboard session. Do not paste session cookies into scripts, docs, support messages, or client-side code. 
{
  "deleted": true,
  "business_id": "biz_123",
  "business_name": "My Business",
  "deleted_at": "2026-05-07T12:00:00.000Z",
  "restore_deadline": "2026-06-06T12:00:00.000Z",
  "message": "Business soft-deleted. Data will be permanently removed in 30 days."
}

​
POST /api/businesses/me/restore

Restores a soft-deleted business within the 30-day grace period. Clears the deletion and re-sets it as your active business. Returns 410 Gone if the 30-day grace period has expired. 
curl -X POST "https://app.neariq.io/api/businesses/me/restore"
Run this from an authenticated dashboard session. Do not paste session cookies into scripts, docs, support messages, or client-side code. 
{
  "restored": true,
  "business_id": "biz_123",
  "business_name": "My Business",
  "message": "Business restored successfully."
}

​
Dashboard business endpoints

The following /api/businesses/me/* endpoints are dashboard endpoints. They use the signed-in app session, not X-NearIQ-Key, and operate on the user’s active personal or organization business. Organization-owned businesses also enforce the matching team permission for write actions.

​
GET /api/businesses/me

Returns the active dashboard business, including plan-visible profile fields and onboarding state. 
curl "https://app.neariq.io/api/businesses/me" \
  -b "session cookie"

{
  "business": {
    "id": "biz_abc123",
    "name": "Joe's Pizza",
    "city": "New York",
    "category": "Pizza restaurant",
    "website": "https://example.com"
  }
}

​
PATCH /api/businesses/me

Updates editable active-business profile fields such as display name, website, category, target customer, and differentiator. 
curl -X PATCH "https://app.neariq.io/api/businesses/me" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "website": "https://example.com", "targetCustomer": "families nearby" }'

{
  "ok": true,
  "business": {
    "id": "biz_abc123",
    "website": "https://example.com"
  }
}

​
GET /api/businesses/me/usage

Returns plan usage and warning state for the active account or organization. 
curl "https://app.neariq.io/api/businesses/me/usage" \
  -b "session cookie"

{
  "plan": "growth",
  "limits": { "competitors": 25, "locations": 3 },
  "usage": { "competitors": 12, "locations": 1 },
  "warnings": []
}

​
GET /api/businesses/me/action-center

Returns the active business Action Center queue. The route reads existing business data, ranks next-best actions with the deterministic action engine, and returns workflow destinations for the dashboard. It does not call paid data providers, generate AI drafts, send messages, or create records. 
curl "https://app.neariq.io/api/businesses/me/action-center?limit=5&tier=money_now" \
  -b "session cookie"

{
  "businessId": "biz_abc123",
  "orgId": null,
  "generatedAt": "2026-06-09T16:12:00.000Z",
  "limit": 5,
  "tier": "money_now",
  "actions": [
    {
      "id": "call_back_missed_call:call_123",
      "type": "call_back_missed_call",
      "tier": "money_now",
      "priority": 8.4,
      "title": "Call back missed call",
      "whyNow": "A customer called recently and no callback is logged.",
      "suggestedChannel": "call",
      "targetTab": "Messaging",
      "actionUrl": "/dashboard?tab=Messaging&action=call_back_missed_call",
      "sendReadiness": {
        "channel": "call",
        "status": "needs_human_review",
        "reason": "Open the workflow and approve the action before contacting the customer."
      }
    }
  ],
  "counts": {
    "total": 1,
    "byTier": {
      "money_now": 1,
      "reputation_risk": 0,
      "conversion_retention": 0,
      "competitive_opportunity": 0,
      "foundational_visibility": 0
    }
  },
  "sources": {
    "leads": 12,
    "conversations": 4,
    "reviewRequests": 3
  },
  "warnings": []
}
Query parameters:
ParameterDescription
limitOptional result cap from 1 to 20. Defaults to 5.
tierOptional tier filter: money_now, reputation_risk, conversion_retention, competitive_opportunity, or foundational_visibility.
The computed Action Center view also reads aggregate persisted feedback by action type when the persistent queue is available. Recent dismissals and failed sends lower an action type inside its tier, while repeated clicks and completions nudge it up. The hard tier order still wins over any feedback adjustment.

​
GET /api/businesses/me/next-best-actions

Returns the persisted Action Center queue for the active business. This route reads next_best_actions, logs a shown event for returned rows, and supports limit, status, and tier filters. Status updates, draft generation, and execution use the child routes documented in the Action Center guide.

​
GET /api/businesses/me/overage-settings

Returns native overage controls for the active personal account or organization, plus current metered usage and live overage cost for the billing cycle. 
curl "https://app.neariq.io/api/businesses/me/overage-settings" \
  -b "session cookie"

{
  "overageSettings": {
    "overageEnabled": false,
    "monthlyOverageCapCents": null,
    "currentPeriodOverageCents": 0,
    "remainingOverageCapCents": null
  },
  "credits": {
    "sms": {
      "balance": 0,
      "planAllowance": 50,
      "overageThisPeriod": 0,
      "overageRate": { "amount": 0.05, "unit": "message" }
    }
  }
}

​
PATCH /api/businesses/me/overage-settings

Updates whether metered usage can continue after a plan allowance is reached. When overage is off, metered actions hard-cap at the plan allowance and charge $0. When overage is on, an optional monthly cap blocks additional overage after the cap would be exceeded. Organization accounts require owner or admin billing permission. 
curl -X PATCH "https://app.neariq.io/api/businesses/me/overage-settings" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "overageEnabled": true, "monthlyOverageCapCents": 2500 }'

{
  "ok": true,
  "overageSettings": {
    "overageEnabled": true,
    "monthlyOverageCapCents": 2500,
    "currentPeriodOverageCents": 0,
    "remainingOverageCapCents": 2500
  }
}

​
GET /api/businesses/me/invoices

Returns Stripe invoices for the active billing account and live current-cycle metered overage cost. If the account has no Stripe customer yet, the endpoint returns an empty invoice list with current usage visibility. 
curl "https://app.neariq.io/api/businesses/me/invoices" \
  -b "session cookie"

{
  "invoices": [
    {
      "id": "in_123",
      "status": "paid",
      "amountDueCents": 7900,
      "amountPaidCents": 7900,
      "currency": "USD",
      "hostedUrl": "https://invoice.stripe.com/...",
      "pdfUrl": "https://pay.stripe.com/invoice/...",
      "lineItems": [
        { "description": "SMS message overage", "amountCents": 500, "quantity": 10 }
      ]
    }
  ],
  "currentCycle": {
    "overageCostCents": 0,
    "overageCost": 0
  }
}

​
Products and questions

EndpointPurpose
GET /api/businesses/me/productsList products and services for the active business.
POST /api/businesses/me/productsCreate a product or service row.
PATCH /api/businesses/me/productsUpdate a product or service row.
DELETE /api/businesses/me/productsDelete a product or service row.
GET /api/businesses/me/questionsList Q&A rows for the active business.
POST /api/businesses/me/questionsCreate a draft answer or save a Q&A row.
curl -X POST "https://app.neariq.io/api/businesses/me/products" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "name": "Family dinner package", "category": "menu", "price": 39 }'

{
  "product": {
    "id": "prod_123",
    "name": "Family dinner package",
    "category": "menu",
    "price": 39
  }
}

curl -X POST "https://app.neariq.io/api/businesses/me/questions" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "action": "draft", "question": "Do you offer gluten-free crust?" }'

{
  "answer": "Yes. We offer gluten-free crust on request."
}

​
Audit, leads, and review response endpoints

EndpointPurpose
POST /api/businesses/me/site-auditRun a bounded website audit for the active business.
GET /api/businesses/me/leadsList scored lead rows.
POST /api/businesses/me/leadsCreate a lead row.
PATCH /api/businesses/me/leadsUpdate lead status or notes.
POST /api/businesses/me/draft-responseDraft a human-reviewable response to a customer review.
GET /api/businesses/me/response-templatesList saved response templates.
POST /api/businesses/me/response-templatesCreate a response template.
PATCH /api/businesses/me/response-templatesUpdate a response template.
DELETE /api/businesses/me/response-templatesDelete a response template.
curl -X POST "https://app.neariq.io/api/businesses/me/site-audit" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "url": "https://example.com", "refresh": true }'

{
  "audit": {
    "score": 82,
    "pagesCrawled": 12,
    "brokenLinks": 1,
    "schemaSuggestions": []
  }
}

curl -X POST "https://app.neariq.io/api/businesses/me/draft-response" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "reviewText": "Great service", "rating": 5, "tone": "friendly" }'

{
  "draft": "Thank you for visiting. We appreciate the kind words."
}
EndpointPurpose
GET /api/businesses/me/review-requestsList review-request sends and status.
POST /api/businesses/me/review-requestsSend a review request by approved channel.
GET /api/businesses/me/sms-consentList SMS opt-in contacts.
POST /api/businesses/me/sms-consentAdd, update, or bulk import consent rows.
GET /api/businesses/me/phone-numberReturn current SMS number or search available numbers.
POST /api/businesses/me/phone-numberProvision a selected number.
DELETE /api/businesses/me/phone-numberRelease the active number.
GET /api/businesses/me/appointment-remindersList appointment reminders.
POST /api/businesses/me/appointment-remindersCreate an appointment reminder.
PATCH /api/businesses/me/appointment-remindersUpdate reminder status or details.
curl -X POST "https://app.neariq.io/api/businesses/me/review-requests" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "customerName": "Jane", "email": "jane@example.com", "channel": "email" }'

{
  "request": {
    "id": "req_123",
    "status": "queued",
    "channel": "email"
  }
}

curl -X POST "https://app.neariq.io/api/businesses/me/sms-consent" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "phone": "+15557654321", "consented": true, "source": "checkout" }'

{
  "ok": true,
  "contact": {
    "phone": "+15557654321",
    "consented": true
  }
}

​
Messaging and social publishing

EndpointPurpose
GET /api/businesses/me/conversationsList conversations or load one thread.
POST /api/businesses/me/conversationsCreate or send a message.
GET /api/businesses/me/social-postsList drafted and scheduled social posts.
POST /api/businesses/me/social-postsCreate a social post draft or schedule.
PATCH /api/businesses/me/social-postsUpdate post status, schedule, or content.
GET /api/businesses/me/publish-targetsList connected publish targets.
POST /api/businesses/me/publish-targetsAdd a publish target.
PATCH /api/businesses/me/publish-targetsUpdate a publish target.
DELETE /api/businesses/me/publish-targetsRemove a publish target.
curl -X POST "https://app.neariq.io/api/businesses/me/social-posts" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "text": "Spring special starts today.", "platforms": ["instagram"], "status": "draft" }'

{
  "post": {
    "id": "post_123",
    "status": "draft",
    "platforms": ["instagram"]
  }
}

​
Listing and citation workflows

EndpointPurpose
GET /api/businesses/me/listing-syncList citation sync status by directory.
POST /api/businesses/me/listing-syncStart listing sync for selected directories.
GET /api/businesses/me/directory-submitList directories with submission status.
POST /api/businesses/me/directory-submitSubmit the active business to one directory.
GET /api/businesses/me/citations/statusReturn citation health and sync status.
POST /api/businesses/me/citations/pushPush corrected business data to supported directories.
curl -X POST "https://app.neariq.io/api/businesses/me/listing-sync" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "action": "sync_all" }'

{
  "ok": true,
  "queued": 8,
  "includedLocationsUsed": 1
}

​
Analytics and intelligence endpoints

EndpointPurpose
GET /api/businesses/me/gbp-insightsReturn first-party listing performance metrics.
GET /api/businesses/me/ai-visibilityReturn AI answer visibility history for the active business.
POST /api/businesses/me/ai-visibility/checkRun an on-demand AI visibility check when limits allow.
GET /api/businesses/me/behavioral-signalsReturn engagement and response-quality signals.
GET /api/businesses/me/gap-analysisReturn cached competitive gap analysis.
POST /api/businesses/me/gap-analysisRefresh gap analysis with optional feedback.
GET /api/businesses/me/trendsReturn market trend rows for the active business.
POST /api/businesses/me/trends/analyzeQueue or refresh trend analysis.
GET /api/businesses/me/activity-metricsReturn activity and engagement metrics.
POST /api/businesses/me/keyword-suggestionsGenerate keyword suggestions for a business/category.
GET /api/businesses/me/link-suggestionsReturn website and listing link recommendations.
POST /api/businesses/me/geo-auditRun a geographic visibility audit.
GET /api/businesses/me/brand-mentionsList detected brand mentions.
PATCH /api/businesses/me/brand-mentionsUpdate mention status or labels.
curl -X POST "https://app.neariq.io/api/businesses/me/ai-visibility/check" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "queries": ["best pizza near me"], "location": "New York, NY" }'

{
  "check": {
    "status": "queued",
    "queries": 1,
    "location": "New York, NY"
  }
}

​
Photos and voice clones

EndpointPurpose
GET /api/businesses/me/photosList business photo metadata.
POST /api/businesses/me/photosUpload or attach a business photo.
DELETE /api/businesses/me/photosRemove a business photo by media name.
GET /api/businesses/me/voice-clonesList consented voice profiles.
POST /api/businesses/me/voice-clonesCreate a consented voice profile.
PATCH /api/businesses/me/voice-clonesUpdate a voice profile.
DELETE /api/businesses/me/voice-clonesDelete a voice profile by ID.
curl "https://app.neariq.io/api/businesses/me/photos" \
  -b "session cookie"

{
  "photos": [
    {
      "mediaName": "locations/photo-1",
      "url": "https://example.com/photo.jpg",
      "category": "exterior"
    }
  ]
}

​
Dashboard business endpoint errors

StatusMeaning
400Invalid request body, missing active business, or unsupported action
401Missing dashboard session
403Plan or organization permission does not allow the requested action
404Business, row, media item, or job not found
409Duplicate or conflicting resource
429Plan or safety limit reached
500Stored data could not be loaded or the requested action failed