Your Business

Returns your business profile — rating, review count, category, address, and linked Google Place ID.

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"

const neariq = new NearIQ({ apiKey: 'niq_your_key_here' })
const business = await neariq.me.get()

{
  "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

Parameter	Type	Default	Description
`limit`	integer	90	Number of most-recent snapshots (max 365)
`from`	ISO date	-	Inclusive start date filter
`to`	ISO 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

Parameter	Type	Default	Description
`limit`	integer	50	Reviews to return (max 200)
`sort`	string	`newest`	`newest`, `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:

Parameter	Description
`limit`	Optional result cap from 1 to 20. Defaults to 5.
`tier`	Optional 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

Endpoint	Purpose
`GET /api/businesses/me/products`	List products and services for the active business.
`POST /api/businesses/me/products`	Create a product or service row.
`PATCH /api/businesses/me/products`	Update a product or service row.
`DELETE /api/businesses/me/products`	Delete a product or service row.
`GET /api/businesses/me/questions`	List Q&A rows for the active business.
`POST /api/businesses/me/questions`	Create 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

Endpoint	Purpose
`POST /api/businesses/me/site-audit`	Run a bounded website audit for the active business.
`GET /api/businesses/me/leads`	List scored lead rows.
`POST /api/businesses/me/leads`	Create a lead row.
`PATCH /api/businesses/me/leads`	Update lead status or notes.
`POST /api/businesses/me/draft-response`	Draft a human-reviewable response to a customer review.
`GET /api/businesses/me/response-templates`	List saved response templates.
`POST /api/businesses/me/response-templates`	Create a response template.
`PATCH /api/businesses/me/response-templates`	Update a response template.
`DELETE /api/businesses/me/response-templates`	Delete 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."
}

Endpoint	Purpose
`GET /api/businesses/me/review-requests`	List review-request sends and status.
`POST /api/businesses/me/review-requests`	Send a review request by approved channel.
`GET /api/businesses/me/sms-consent`	List SMS opt-in contacts.
`POST /api/businesses/me/sms-consent`	Add, update, or bulk import consent rows.
`GET /api/businesses/me/phone-number`	Return current SMS number or search available numbers.
`POST /api/businesses/me/phone-number`	Provision a selected number.
`DELETE /api/businesses/me/phone-number`	Release the active number.
`GET /api/businesses/me/appointment-reminders`	List appointment reminders.
`POST /api/businesses/me/appointment-reminders`	Create an appointment reminder.
`PATCH /api/businesses/me/appointment-reminders`	Update 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
  }
}

Endpoint	Purpose
`GET /api/businesses/me/conversations`	List conversations or load one thread.
`POST /api/businesses/me/conversations`	Create or send a message.
`GET /api/businesses/me/social-posts`	List drafted and scheduled social posts.
`POST /api/businesses/me/social-posts`	Create a social post draft or schedule.
`PATCH /api/businesses/me/social-posts`	Update post status, schedule, or content.
`GET /api/businesses/me/publish-targets`	List connected publish targets.
`POST /api/businesses/me/publish-targets`	Add a publish target.
`PATCH /api/businesses/me/publish-targets`	Update a publish target.
`DELETE /api/businesses/me/publish-targets`	Remove 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

Endpoint	Purpose
`GET /api/businesses/me/listing-sync`	List citation sync status by directory.
`POST /api/businesses/me/listing-sync`	Start listing sync for selected directories.
`GET /api/businesses/me/directory-submit`	List directories with submission status.
`POST /api/businesses/me/directory-submit`	Submit the active business to one directory.
`GET /api/businesses/me/citations/status`	Return citation health and sync status.
`POST /api/businesses/me/citations/push`	Push 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

Endpoint	Purpose
`GET /api/businesses/me/gbp-insights`	Return first-party listing performance metrics.
`GET /api/businesses/me/ai-visibility`	Return AI answer visibility history for the active business.
`POST /api/businesses/me/ai-visibility/check`	Run an on-demand AI visibility check when limits allow.
`GET /api/businesses/me/behavioral-signals`	Return engagement and response-quality signals.
`GET /api/businesses/me/gap-analysis`	Return cached competitive gap analysis.
`POST /api/businesses/me/gap-analysis`	Refresh gap analysis with optional feedback.
`GET /api/businesses/me/trends`	Return market trend rows for the active business.
`POST /api/businesses/me/trends/analyze`	Queue or refresh trend analysis.
`GET /api/businesses/me/activity-metrics`	Return activity and engagement metrics.
`POST /api/businesses/me/keyword-suggestions`	Generate keyword suggestions for a business/category.
`GET /api/businesses/me/link-suggestions`	Return website and listing link recommendations.
`POST /api/businesses/me/geo-audit`	Run a geographic visibility audit.
`GET /api/businesses/me/brand-mentions`	List detected brand mentions.
`PATCH /api/businesses/me/brand-mentions`	Update 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

Endpoint	Purpose
`GET /api/businesses/me/photos`	List business photo metadata.
`POST /api/businesses/me/photos`	Upload or attach a business photo.
`DELETE /api/businesses/me/photos`	Remove a business photo by media name.
`GET /api/businesses/me/voice-clones`	List consented voice profiles.
`POST /api/businesses/me/voice-clones`	Create a consented voice profile.
`PATCH /api/businesses/me/voice-clones`	Update a voice profile.
`DELETE /api/businesses/me/voice-clones`	Delete 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

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

API Reference

Endpoints

Webhooks

GET /me/snapshots

GET /me/reviews

GET /me/gbp-health

DELETE /api/businesses/me/delete

POST /api/businesses/me/restore

Dashboard business endpoints

GET /api/businesses/me

PATCH /api/businesses/me

GET /api/businesses/me/usage

GET /api/businesses/me/action-center

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

GET /api/businesses/me/overage-settings

PATCH /api/businesses/me/overage-settings

GET /api/businesses/me/invoices

Products and questions

Audit, leads, and review response endpoints

Listing and citation workflows

Analytics and intelligence endpoints

Photos and voice clones

Dashboard business endpoint errors

​GET /me/snapshots

​GET /me/reviews

​GET /me/gbp-health

​DELETE /api/businesses/me/delete

​POST /api/businesses/me/restore

​Dashboard business endpoints

​GET /api/businesses/me

​PATCH /api/businesses/me

​GET /api/businesses/me/usage

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

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

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

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

​GET /api/businesses/me/invoices

​Products and questions

​Audit, leads, and review response endpoints

​Review requests, SMS consent, and phone number

​Messaging and social publishing

​Listing and citation workflows

​Analytics and intelligence endpoints

​Photos and voice clones

​Dashboard business endpoint errors

GET /me/snapshots

GET /me/reviews

GET /me/gbp-health

DELETE /api/businesses/me/delete

POST /api/businesses/me/restore

Dashboard business endpoints

GET /api/businesses/me

PATCH /api/businesses/me

GET /api/businesses/me/usage

GET /api/businesses/me/action-center

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

GET /api/businesses/me/overage-settings

PATCH /api/businesses/me/overage-settings

GET /api/businesses/me/invoices

Products and questions

Audit, leads, and review response endpoints

Review requests, SMS consent, and phone number

Messaging and social publishing

Listing and citation workflows

Analytics and intelligence endpoints

Photos and voice clones

Dashboard business endpoint errors