Skip to main content

Partner Integration

White-label partners set up and manage XAPP AI for their own businesses through the partner API. Your system sends an event to set up a business. XAPP AI builds the assistant, the website widget, Book Online and a booking link. Your system then reads back the business's status, its install snippet, white-label install steps, and its leads and traffic.

Responsibilities​

XAPP AIPartner
Partner API and its infrastructure✅
Assistant runtime, management and QA✅
Templates for your businesses✅
Sending setup events for your businesses✅
Sending install steps to your businesses✅
Reading status and analytics✅

Setup flow​

Every call in the life of one business, from the partner's first key to its monthly report. Calls in an opt box are optional, and a loop box repeats. The numbered sections below describe each call.

Basics​

Base URLhttps://api.xapp.ai/partner/v1
AuthenticationAuthorization: Bearer <partner key> on every request
FormatJSON in and out
Business idYour own id for each business (businessId), up to 128 letters, digits, ., _, : or -

A key belongs to one partner organization. It can only see and change that organization's businesses. A business that belongs to someone else answers 404, exactly like one that does not exist.

Check that a key works with GET /partner/v1/ping:

curl https://api.xapp.ai/partner/v1/ping \
-H "Authorization: Bearer $PARTNER_KEY"
{ "ok": true, "partnerOrgId": "your-org-id" }

A missing or wrong key answers 401.

Endpoints​

Method and pathWhat it does
GET /partner/v1/pingConfirms the key works and names its organization
POST /partner/v1/eventsSends an event, for example to set up a business
GET /partner/v1/businessesLists your businesses, a page at a time
GET /partner/v1/businesses/{businessId}One business: status, snippet, install steps, booking link
GET /partner/v1/businesses/{businessId}/analyticsOne business's leads and website traffic over a date range
POST /partner/graphqlThe same reads as one GraphQL endpoint

Setting up a business​

1. Send the setup event​

curl -X POST https://api.xapp.ai/partner/v1/events \
-H "Authorization: Bearer $PARTNER_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "01JC8Z6Q4M2V7Y3K9T5R0B1XWE",
"type": "business.setup_requested",
"version": "1",
"occurredAt": "2026-11-01T15:00:00Z",
"businessId": "biz-48213",
"data": {
"businessName": "Green Valley Lawn Care",
"website": "https://greenvalleylawn.example",
"googleBusinessProfile": "ChIJN1t_tDeuEmsRUsoyG83frY4",
"phone": "+15555550123",
"streetAddress": "1200 Main St",
"city": "Austin",
"state": "TX",
"zip": "78701",
"integrations": [
{ "type": "partner-crm", "config": { "campaignId": "campaign-991" } }
]
}
}'
  • id is your id for the event. Events are de-duplicated on it, so after a timeout or a 5xx, resend with the same id.

  • businessName is the only required field. XAPP AI builds everything the rest allows:

    • the website widget (chat and forms) when there is a website
    • Book Online (booking through Reserve with Google) when a Google Business Profile is found
    • a booking link in every case
  • integrations says where the business's leads go. Each entry has:

    • type: an integration XAPP AI has set up for your organization. Your account manager gives you its name.
    • config: values only you know, such as a campaign id in your own system. Keys the integration does not use are ignored.

    Leave integrations out to use your organization's default. The API reference has every field of the event.

ResponseMeaning
202Stored, and it will be worked shortly
200An event with this id was already received. Nothing new happens.
400Not valid. Every failing field is listed, and nothing was stored.
429, 5xxRetry with backoff; see below

Sending the setup event again for a business that is already set up changes nothing. The exception is a failed business, which is worked again (see the statuses below).

To retry, wait longer between each attempt, for example 1, 2, 4 and then 8 seconds, adding a little random jitter. Keep the same id throughout. A resent event is never worked twice.

2. Follow its status​

Read the business with GET /partner/v1/businesses/{businessId}. You can read it as soon as the setup event is accepted: until it is built, it has status: provisioning and no widget, bookOnline or bookingLink, and integrations is empty.

With a webhook registered, we tell you every change as it happens. Without one, poll the business, for example every 30 seconds while it is provisioning; setup usually takes under a minute. Its status moves through:

StatusMeaning
provisioningBeing built, or waiting to retry a step that may pass
in_reviewBuilt, and in XAPP AI's quality review
google_pendingReviewed; Book Online is waiting on Google. It moves to live when Google sends Book Online its first booking traffic.
liveReady. A business without a Google Business Profile goes straight here from review.
stoppedTurned off. Version 1 of the API has no event to stop a business; ask your account manager.
failedSetup stopped. failureReason, a sentence for a person to read, says why: a problem with the request or your setup, or a failure on XAPP AI's side that kept recurring. Fix the cause if there is one, then send the setup event again with a new id. The business is then worked again.

A failed business:

{
"businessId": "biz-48213",
"businessName": "Green Valley Lawn Care",
"status": "failed",
"failureReason": "Setup failed on our side after several tries, and we have been alerted. Send the setup event again with a new id to retry.",
"createdAt": "2026-11-10T15:00:04.000Z",
"updatedAt": "2026-11-10T15:36:12.000Z",
"integrations": []
}

failureReason is present only when status is failed.

3. Send the install steps to the business​

Once the widget is built, the business response carries widget.snippet, the script tag for the business's website, and widget.instructions. The instructions are white-label install steps in plain Markdown, with the snippet already in them, written for the business owner or their web person. They name neither XAPP AI nor Studio, so you can paste them into an email as they are.

Ask for the business's website platform with ?platform=:

curl "https://api.xapp.ai/partner/v1/businesses/biz-48213?platform=wix" \
-H "Authorization: Bearer $PARTNER_KEY"

Platforms with their own steps (the API reference lists the current set):

  • wordpress, wix, squarespace, shopify, godaddy, duda
  • framer, drupal, joomla, zyro (Hostinger)
  • generic, for any other site

Without platform you get the generic steps. widget.instructions.availablePlatforms lists every platform there are steps for.

The response also has:

  • bookingLink.
  • bookOnline when the business has a Google Business Profile. Its status is pending_google until Google sends Book Online its first booking traffic, then live, with liveSince.
  • agent: the business's MCP server for AI agents (mcpUrl, manifestUrl, serverCardUrl), which the snippet advertises on the business's website. agent.tags are the three discovery tags, and agent.instructions are white-label steps for adding them to the platform's page header, for the same ?platform= as the widget's. See AI Agent Discovery.

Listing businesses​

GET /partner/v1/businesses returns your businesses in businessId order, 50 at a time by default (limit takes 1 to 100). Each one is shaped like the single-business response, without the install steps. Filter by status, for example ?status=live.

Pass nextCursor back as cursor for the next page. The last page has no nextCursor.

curl "https://api.xapp.ai/partner/v1/businesses?status=live&limit=100" \
-H "Authorization: Bearer $PARTNER_KEY"

Analytics​

GET /partner/v1/businesses/{businessId}/analytics?from=&to= returns one business's leads and website traffic over a date range. from and to are ISO 8601 dates. Without them you get the last 30 days. A range can be at most 366 days.

{
"businessId": "biz-48213",
"from": "2026-10-01T00:00:00.000Z",
"to": "2026-11-01T00:00:00.000Z",
"leads": { "total": 12, "highValue": 3 },
"traffic": {
"visitors": 340,
"uniqueVisitors": 290,
"pageViews": 900,
"chatOpens": 25,
"sessions": { "website": 300, "bookOnline": 20, "bookingLink": 10 },
"submissions": { "website": 8, "bookOnline": 2, "bookingLink": 1 },
"sources": [
{ "channel": "google_search", "sessions": 120 },
{ "channel": "direct", "sessions": 80 }
]
},
"agents": {
"visitors": 14,
"formSubmits": 2,
"byAgent": [
{ "name": "ChatGPT-User", "visitors": 9, "formSubmits": 2 },
{ "name": "Claude-User", "visitors": 5, "formSubmits": 0 }
],
"aiReferrals": [{ "name": "chatgpt", "visitors": 6 }],
"crawlers": 40
}
}
FieldMeaning
leads.totalLeads received in the range. Test and abandoned leads are left out.
leads.highValueOf those, leads classified as high value
traffic.visitorsVisitors to the business's own website, counted by IP address. Bots and crawlers are left out.
traffic.uniqueVisitorsDistinct browsers on the business's website
traffic.pageViewsPage views on the business's website
traffic.chatOpensChat windows opened
traffic.sessionsSessions on each channel: the business's website, bookOnline (Reserve with Google), and the bookingLink
traffic.submissionsBooking form submissions on each channel
traffic.sourcesArrivals on the business's website by channel, largest first. Channels: google_search, google_maps, facebook, instagram, other_social, ai, other_search, email, referral and direct.
agents.visitorsAI agents browsing for someone (ChatGPT's agent, Claude, …) that loaded the widget on the business's website
agents.formSubmitsOf those, how many submitted a form
agents.byAgentThose agents by name, with their visitors and form submits, most visitors first
agents.aiReferralsPeople an AI assistant (chatgpt, perplexity, google-ai-overview, …) sent to the website, by assistant
agents.crawlersSearch engines and other crawlers that loaded the widget

visitors, uniqueVisitors, pageViews and agents are null when they could not be read, so an outage never shows up as zero visitors. A business that is not set up yet reports zeros.

GraphQL​

POST https://api.xapp.ai/partner/graphql offers the same reads in one request, with the same keys. Introspection is on, so GraphQL tools can load the schema from the endpoint.

query LiveBusinesses($after: String) {
partner {
businesses(status: live, first: 25, after: $after) {
businesses {
businessId
businessName
bookingLink
agent { mcpUrl }
widget {
snippet
instructions(platform: "wordpress") { markdown }
}
analytics(from: "2026-10-01T00:00:00Z", to: "2026-11-01T00:00:00Z") {
leads { total highValue }
traffic { visitors chatOpens submissions { website bookOnline bookingLink } }
agents { visitors formSubmits aiReferrals { name visitors } }
}
}
nextCursor
}
}
}
curl -X POST https://api.xapp.ai/partner/graphql \
-H "Authorization: Bearer $PARTNER_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "{ partner { business(businessId: \"biz-48213\") { status analytics { leads { total } } } } }"}'
  • Enum values such as status: live are written without quotes in GraphQL, where REST takes ?status=live.
  • One request can ask for analytics on at most 25 businesses. Page with first: 25 when you want each business's analytics.
  • partner.business(businessId:) is null for a business that does not exist or is another partner's.
  • Bad input, such as an unknown platform, an invalid date range or an unknown cursor, returns an error with extensions.code set to BAD_USER_INPUT.
  • GraphQL only reads. A mutation or subscription returns an error with extensions.code set to GRAPHQL_VALIDATION_FAILED. To make a change, send an event.

Webhooks​

Register a webhook and we send your system an event whenever one of your businesses changes, so you don't have to poll.

Register it​

On your organization's Developer Tools page in Studio (owners and admins):

  1. Enter an https URL on your servers and click Save. It must use a public host name, not an IP address or a local name.
  2. Copy the signing secret. It is shown this once. Studio keeps only its last four characters.
  3. Click Send a test event to check your endpoint. Studio shows how it answered.

An organization has one webhook. Changing its URL keeps the secret. Rotate secret makes a new one and the old one stops signing at once, so switch your system over straight away. Delete webhook stops the events. The page also shows how the last delivery went.

What we send​

Each event is a POST with a JSON body in the same envelope as the events you send us:

{
"id": "evt_5f0c2a9e7d1b4c3a8e6f0d2b9a7c1e4f",
"type": "business.live",
"version": "1",
"occurredAt": "2026-11-13T15:20:00.000Z",
"businessId": "biz-48213",
"data": { "business": { "businessId": "biz-48213", "status": "live", "…": "…" } }
}
HeaderValue
Content-Typeapplication/json
X-XAPP-EventThe event type
X-XAPP-Event-IdThe event id
X-XAPP-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">, signed with your secret
EventSent whendata
business.setup_completedA business is builtbusiness
business.setup_failedSetup stoppedfailureReason
business.liveA business is readybusiness
business.book_online.liveGoogle sent Book Online its first booking trafficgooglePlaceId, liveSince
business.stoppedA business is turned offbusiness
business.status_changedEvery status change, after the events abovepreviousStatus, status, business
webhook.testYou click Send a test eventmessage

business is the business as GET /partner/v1/businesses returns it, without the install steps; read the business for those. business.status_changed is the one event to handle if you only want status: every change sends it.

Check the signature​

Compute the HMAC-SHA256 of "<t>.<raw body>" with your secret, compare it to v1 in constant time, and reject a t more than 5 minutes old:

const crypto = require("crypto");

function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Use the body exactly as received, before any JSON parsing.

Answering and retries​

  • Answer 2xx within 10 seconds, then do the work. Anything else, a redirect or no answer is a failed delivery.
  • A failed delivery is tried again after 1 minute, 5 minutes, 30 minutes and 2 hours, then every 6 hours: about a day in all. After that we are alerted and stop.
  • One business's events arrive in order, and a failing event holds back only that business's later ones. Still sort by occurredAt, and ignore a status older than one you have.
  • An event can arrive more than once. De-duplicate on id.

Errors​

Errors other than GraphQL's are JSON with a message, for example {"message": "Business not found"}.

StatusMeaning
400The request is invalid. The message says why.
401No key, or a key that is wrong or revoked
403The key cannot use this route, for example an organization API key that is not a partner key. See also the note below.
404No such business for your organization
429Throttled. Retry with backoff.

A firewall in front of the API also answers 403 to a body that looks like an attack, such as a website of javascript:alert(1). The request never reaches the API. Check the event's fields against the API reference: websites must be http or https URLs.