Developer & Reporting API: Index & Authentication

The ProfilePilot Developer & Reporting API (/api/v1/*) lets your engineering, BI, and data-warehouse teams sync store master records and pull live reporting data across Locations, Reputation, WhatsApp Commerce, Email Marketing, Omnichannel Campaigns, Smart Inbox, Social Inbox, and Insights.

Commercial Plan & Monthly Call Allowance

• Add-on Requirement: Developer API Access ($50/month minimum spend) must be enabled under Settings → Usage & Add-ons (/dashboard/settings/billing).
• Included Monthly Calls: Your $50/month minimum covers your first 500,000 API calls per calendar month (UTC) across all keys in your organisation.
• API Call Top-Up Blocks: If your organisation approaches or reaches its monthly call allowance, you can purchase instant API Call Top-Up Blocks directly under Settings → Developer API (/dashboard/settings/developer) or Settings → Usage & Add-ons (/dashboard/settings/billing) using the same self-serve block model as LocalSEO Grid Credits:
• 1 Block (`+100,000 calls`) — $12.00
• 5 Blocks (`+500,000 calls`) — $50.00
• 10 Blocks (`+1,000,000 calls`) — $90.00
• Live Metering: Track your current month usage at Settings → Developer API (/dashboard/settings/developer) or inspect the rate-limit headers returned on every response (meta.api_usage in JSON payloads and X-RateLimit-* HTTP headers).

Authentication & Request Headers

Create an API key at Settings → Developer API (/dashboard/settings/developer). Both ppapi_<org>_<secret> and pploc_<org>_<secret> keys are accepted on all /api/v1/* routes as long as the key holds the required scope. Call the API from your backend server, ETL runner, or BI connector — never expose secret keys in browser or mobile client code.

• Authorization: Bearer ppapi_your_secret_key (required) — Your organisation-scoped API key.
• x-org-id: YOUR_ORGANISATION_UUID (*optional*) — Your organisation UUID. Because each ppapi_ / pploc_ key is already bound to a single organisation, x-org-id is optional; if supplied, it must match the key’s organisation or the request is rejected with 403 Forbidden.
• Content-Type: application/json (*required on POST requests*).

Rate-Limit & Metering Response Headers (meta Envelope)

Every reporting endpoint returns HTTP metering headers and appends a meta object to the JSON response body:

• X-Api-Usage-Month / meta.api_usage.month — Current UTC billing month (YYYY-MM).
• X-RateLimit-Limit / meta.api_usage.limit — Monthly included call allowance (500000).
• X-RateLimit-Used / meta.api_usage.used — Total authenticated /api/v1/* calls made by your organisation this month.
• X-RateLimit-Remaining / meta.api_usage.remaining — Remaining calls in your included monthly tier.

Available API Scopes & Product Entitlement Gating

Developer API Access unlocks programmatic access only for the products your organisation is actively subscribed to. Unsubscribed product scopes are disabled in Settings → Developer API and return 403 Forbidden if called:

• locations:read & locations:write — Requires an active Locations & Reputation plan.
• reports:read, reputation:read & social:read — Requires an active Locations & Reputation plan.
• whatsapp:read — Requires WhatsApp Commerce (for /api/v1/whatsapp/orders* and /api/v1/whatsapp/reports/finance) or WhatsApp Commerce / Authentication (for /api/v1/whatsapp/reports/usage).
• email:read — Requires an active Email Marketing plan.
• marketing:read — Requires Locations & Reputation (for Social Posts) and/or WhatsApp Commerce (for WhatsApp Campaigns).
• inbox:read — Requires Smart Inbox entitlement.
• insights:read — Requires an active Insights subscription (and True Attribution event breakdowns require an Insights DIWM or DIFM plan).

Standard Query Parameters & HTTP Status Codes

• startDate & endDate (YYYY-MM-DD, optional) — UTC date window for reporting endpoints (defaults to the last 30 days when omitted; maximum range 366 days).
• limit & offset — Pagination controls on list endpoints (limit default 100, max 500 on reporting routes or 100 on /api/v1/locations; offset default 0).
• HTTP Status Codes:
• 200 OK — Request succeeded.
• 400 Bad Request — Invalid query parameter, malformed JSON body, or invalid enum filter.
• 401 Unauthorized — Missing, malformed, or revoked Authorization: Bearer key.
• 403 Forbidden — Developer API Access add-on disabled, required product subscription inactive, x-org-id mismatch, or API key missing the required scope.
• 404 Not Found — Target resource (store_code or order id) does not exist in your organisation.
• 429 Too Many Requests — Monthly Developer API call allowance reached (used >= limit). Top up additional API call blocks (+100k, +500k, or +1M calls) in Settings → Developer API or Settings → Usage & Add-ons to resume immediately.
• 500 Internal Server Error — Unexpected server error; safe to retry with exponential backoff.