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.
- API reference: api.xapp.ai/partner/docs lists every endpoint with request and response shapes.
- OpenAPI spec: api.xapp.ai/partner/openapi.json, for generating a client.
- API keys: created in Studio on your organization's Developer Tools page. See Partner API Keys.
Responsibilities
| XAPP AI | Partner | |
|---|---|---|
| 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 URL | https://api.xapp.ai/partner/v1 |
| Authentication | Authorization: Bearer <partner key> on every request |
| Format | JSON in and out |
| Business id | Your 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 path | What it does |
|---|---|
GET /partner/v1/ping | Confirms the key works and names its organization |
POST /partner/v1/events | Sends an event, for example to set up a business |
GET /partner/v1/businesses | Lists 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}/analytics | One business's leads and website traffic over a date range |
POST /partner/graphql | The 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" } }
]
}
}'
-
idis your id for the event. Events are de-duplicated on it, so after a timeout or a5xx, resend with the sameid. -
businessNameis 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
- the website widget (chat and forms) when there is a
-
integrationssays 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
integrationsout to use your organization's default. The API reference has every field of the event.
| Response | Meaning |
|---|---|
202 | Stored, and it will be worked shortly |
200 | An event with this id was already received. Nothing new happens. |
400 | Not valid. Every failing field is listed, and nothing was stored. |
429, 5xx | Retry 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:
| Status | Meaning |
|---|---|
provisioning | Being built, or waiting to retry a step that may pass |
in_review | Built, and in XAPP AI's quality review |
google_pending | Reviewed; Book Online is waiting on Google. It moves to live when Google sends Book Online its first booking traffic. |
live | Ready. A business without a Google Business Profile goes straight here from review. |
stopped | Turned off. Version 1 of the API has no event to stop a business; ask your account manager. |
failed | Setup 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,dudaframer,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.bookOnlinewhen the business has a Google Business Profile. Itsstatusispending_googleuntil Google sends Book Online its first booking traffic, thenlive, withliveSince.agent: the business's MCP server for AI agents (mcpUrl,manifestUrl,serverCardUrl), which the snippet advertises on the business's website.agent.tagsare the three discovery tags, andagent.instructionsare 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
}
}
| Field | Meaning |
|---|---|
leads.total | Leads received in the range. Test and abandoned leads are left out. |
leads.highValue | Of those, leads classified as high value |
traffic.visitors | Visitors to the business's own website, counted by IP address. Bots and crawlers are left out. |
traffic.uniqueVisitors | Distinct browsers on the business's website |
traffic.pageViews | Page views on the business's website |
traffic.chatOpens | Chat windows opened |
traffic.sessions | Sessions on each channel: the business's website, bookOnline (Reserve with Google), and the bookingLink |
traffic.submissions | Booking form submissions on each channel |
traffic.sources | Arrivals 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.visitors | AI agents browsing for someone (ChatGPT's agent, Claude, …) that loaded the widget on the business's website |
agents.formSubmits | Of those, how many submitted a form |
agents.byAgent | Those agents by name, with their visitors and form submits, most visitors first |
agents.aiReferrals | People an AI assistant (chatgpt, perplexity, google-ai-overview, …) sent to the website, by assistant |
agents.crawlers | Search 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: liveare written without quotes in GraphQL, where REST takes?status=live. - One request can ask for
analyticson at most 25 businesses. Page withfirst: 25when you want each business's analytics. partner.business(businessId:)isnullfor 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.codeset toBAD_USER_INPUT. - GraphQL only reads. A mutation or subscription returns an error with
extensions.codeset toGRAPHQL_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):
- Enter an
httpsURL on your servers and click Save. It must use a public host name, not an IP address or a local name. - Copy the signing secret. It is shown this once. Studio keeps only its last four characters.
- 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", "…": "…" } }
}
| Header | Value |
|---|---|
Content-Type | application/json |
X-XAPP-Event | The event type |
X-XAPP-Event-Id | The event id |
X-XAPP-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">, signed with your secret |
| Event | Sent when | data |
|---|---|---|
business.setup_completed | A business is built | business |
business.setup_failed | Setup stopped | failureReason |
business.live | A business is ready | business |
business.book_online.live | Google sent Book Online its first booking traffic | googlePlaceId, liveSince |
business.stopped | A business is turned off | business |
business.status_changed | Every status change, after the events above | previousStatus, status, business |
webhook.test | You click Send a test event | message |
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
2xxwithin 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"}.
| Status | Meaning |
|---|---|
400 | The request is invalid. The message says why. |
401 | No key, or a key that is wrong or revoked |
403 | The key cannot use this route, for example an organization API key that is not a partner key. See also the note below. |
404 | No such business for your organization |
429 | Throttled. 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.