{"openapi":"3.0.3","info":{"title":"XAPP Partner API","description":"For white-label partners that set up and manage XAPP lead generation for their own businesses.\n\nA partner **sends events** to `POST /partner/v1/events` to ask for changes, and **reads state** with `GET /partner/v1/businesses/{businessId}`. Every business is keyed by the partner's own id for it (`businessId`).\n\nEvery request carries a partner key: `Authorization: Bearer <partner key>`. XAPP issues the keys; each one belongs to one partner organization and can only see and change that partner's businesses. A revoked key stops working within 5 minutes.\n\nAn event is stored before it is acknowledged. A `2xx` means it cannot be lost, and resending an event with the same `id` is always safe.","version":"1.0.0","contact":{"name":"XAPP AI","url":"https://xapp.ai"}},"servers":[{"url":"https://api.xapp.ai"}],"security":[{"PartnerKey":[]}],"tags":[{"name":"Events","description":"Changes a partner asks for."},{"name":"Businesses","description":"The current state of a partner's businesses."},{"name":"Keys","description":"Checking a partner key."},{"name":"GraphQL","description":"The partner API's reads as one GraphQL endpoint, behind the same key."}],"paths":{"/partner/v1/ping":{"get":{"operationId":"ping","tags":["Keys"],"summary":"Check a partner key","description":"Answers with the partner organization the key belongs to. Use it to check a new or rotated key end to end.","responses":{"200":{"description":"The key works.","content":{"application/json":{"schema":{"type":"object","required":["ok","partnerOrgId"],"properties":{"ok":{"type":"boolean","enum":[true]},"partnerOrgId":{"type":"string","description":"The partner organization the key acts as."}}},"example":{"ok":true,"partnerOrgId":"acme-partner"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/partner/v1/events":{"post":{"operationId":"sendEvent","tags":["Events"],"summary":"Send an event","description":"Stores the event, then answers. The work happens afterwards: check its outcome with `GET /partner/v1/businesses/{businessId}`.\n\nOne business's events are worked in the order they were received. Events are de-duplicated on `id`, so resend with the same `id` after a timeout or a `5xx`.\n\nVersion 1 accepts three event types:\n\n- `business.setup_requested`: XAPP builds everything it can for the business: the web widget (chat and forms) when there is a website, Book Online when a Google Business Profile is found, and a booking link always. Sending it again for a `businessId` that is already set up changes nothing.\n- `lead.captured`: a lead the business got on another platform (an ad platform, a marketplace, another form). It is analyzed and shown on the business's dashboard with the platform as its source.\n- `call.completed`: a phone call your AI phone agent took for the business. XAPP analyzes the transcript: what happened on the call, and the lead captured on it. Every call appears on the dashboard; a call that captured a lead adds that lead, with the transcript attached. Contact details you send are used first; anything missing is taken from the transcript.\n\nA lead or a call must name a business already sent in `business.setup_requested`; it waits for that setup to finish. By default these leads only appear on the dashboard: they are not sent to the business's lead emails, texts or CRM connection, since the business usually has them already. Set `data.deliver` to `true` to send them on as well. They never count toward a free lead allowance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SetupRequestedEvent"},{"$ref":"#/components/schemas/LeadCapturedEvent"},{"$ref":"#/components/schemas/CallCompletedEvent"}],"discriminator":{"propertyName":"type","mapping":{"business.setup_requested":"#/components/schemas/SetupRequestedEvent","lead.captured":"#/components/schemas/LeadCapturedEvent","call.completed":"#/components/schemas/CallCompletedEvent"}}},"examples":{"setup":{"summary":"Set up a business","value":{"id":"01JC8Z6Q4M2V7Y3K9T5R0B1XWE","type":"business.setup_requested","version":"1","occurredAt":"2026-11-10T15: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"}}]}}},"lead":{"summary":"A lead from another platform","value":{"id":"lead-20261117-0042","type":"lead.captured","version":"1","occurredAt":"2026-11-17T17:30:00Z","businessId":"biz-48213","data":{"source":{"platform":"Facebook Lead Ads"},"contact":{"name":"Jordan Reyes","phone":"+15125550188","email":"jordan@example.com","address":{"street":"12 Elm St","city":"Austin","state":"TX","zip":"78701"}},"request":"Quote for weekly mowing","contactMethod":"form","fields":{"budget":"$200/mo"}}}},"call":{"summary":"A call your AI phone agent took","value":{"id":"call-20261117-0031","type":"call.completed","version":"1","occurredAt":"2026-11-17T17:30:00Z","businessId":"biz-48213","data":{"source":{"platform":"AI Receptionist"},"direction":"inbound","durationSeconds":184,"callerPhone":"+15125550188","agentType":"ai","recordingUrl":"https://recordings.example.com/call-31.mp3","transcript":{"turns":[{"speaker":"agent","text":"Thanks for calling Green Valley, how can I help?","at":"2026-11-17T17:27:00Z"},{"speaker":"caller","text":"My sprinklers are leaking. This is Jordan, jordan@example.com."}]},"contact":{"name":"Jordan Reyes"}}}}}}}},"responses":{"200":{"description":"An event with this `id` was already received. Nothing new happens.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReceipt"},"example":{"id":"01JC8Z6Q4M2V7Y3K9T5R0B1XWE","status":"duplicate"}}}},"202":{"description":"Stored. It will be worked shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReceipt"},"example":{"id":"01JC8Z6Q4M2V7Y3K9T5R0B1XWE","status":"accepted"}}}},"400":{"description":"The body is not JSON, or the event fails validation. Every failing field is listed. Nothing was stored, so fix it and resend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"example":{"message":"Invalid event","errors":[{"field":"data.phone","message":"must be E.164, e.g. +15555550123"},{"field":"data.state","message":"must be a two-letter code, e.g. TX"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key is not allowed here, or a firewall in front of the API refused a body that looks like an attack (for example a `javascript:` URL). Such a body would fail validation anyway: check the fields against this schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"413":{"description":"The body is over 262,144 bytes (256 KB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"422":{"description":"A `lead.captured` or `call.completed` names a `businessId` you have not sent in `business.setup_requested`. Nothing was stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"example":{"message":"Unknown business","errors":[{"field":"businessId","message":"is not a business you have set up; send business.setup_requested first"}]}}}},"429":{"description":"Throttled. Retry later with the same `id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"500":{"description":"The event could not be stored. Retry with the same `id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}}}}},"/partner/v1/businesses":{"get":{"operationId":"listBusinesses","tags":["Businesses"],"summary":"List businesses","description":"The partner's businesses, a page at a time, in `businessId` order. Each is as `GET /partner/v1/businesses/{businessId}` gives it, without `widget.instructions`; ask for one business to get its install steps.\n\nPass `nextCursor` back as `cursor` for the next page. There are no more pages when `nextCursor` is absent. Every page but the last holds `limit` businesses; a page that ends exactly where the matches do can still carry a `nextCursor`, leading to an empty last page.","parameters":[{"name":"limit","in":"query","required":false,"description":"Businesses per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the page before. Opaque: pass it back as it came.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only businesses in this status.","schema":{"type":"string","enum":["provisioning","in_review","google_pending","live","stopped","failed"]},"example":"live"}],"responses":{"200":{"description":"A page of businesses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessPage"},"example":{"businesses":[{"businessId":"biz-48213","businessName":"Green Valley Lawn Care","status":"live","createdAt":"2026-11-10T15:00:04.000Z","updatedAt":"2026-11-10T15:06:12.000Z","integrations":[],"widget":{"widgetId":"wgt_8d21","features":{"chat":true,"form":true},"snippet":"<script id=\"xapp-js\" src=\"https://widget.xapp.ai/xapp-chat-widget.js?key=wgt_8d21\" nitro-exclude defer></script>","live":false},"bookingLink":"https://book.example/?key=frm_19ce","agent":{"mcpUrl":"https://agentic.xapp.ai/green-valley-lawn-care/mcp","manifestUrl":"https://agentic.xapp.ai/green-valley-lawn-care/.well-known/mcp/manifest.json","serverCardUrl":"https://agentic.xapp.ai/green-valley-lawn-care/mcp/server-card","tags":"<link rel=\"mcp-server\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/mcp\">\n<link rel=\"mcp-manifest\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/.well-known/mcp/manifest.json\">\n<link rel=\"mcp-server-card\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/mcp/server-card\">"}}],"nextCursor":"eyJhZnRlciI6ImJpei00ODIxMyJ9"}}}},"400":{"description":"A bad `limit`, `cursor` or `status`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"},"example":{"message":"limit must be a whole number from 1 to 100"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/partner/v1/businesses/{businessId}":{"get":{"operationId":"getBusiness","tags":["Businesses"],"summary":"Get a business","description":"Everything about one of the partner's businesses, in the same shapes the events use. A business belonging to another partner is a `404`, exactly like one that does not exist.","parameters":[{"name":"businessId","in":"path","required":true,"description":"The partner's own id for the business, as sent in its events. URL-encode it.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"},"example":"biz-48213"},{"name":"platform","in":"query","required":false,"description":"The business's website platform, for install steps written for it. Without it the steps are the generic ones (paste before `</body>` on every page). Applies to both `widget.instructions` and `agent.instructions`.","schema":{"type":"string","enum":["drupal","duda","framer","generic","godaddy","joomla","shopify","squarespace","wix","wordpress","zyro"]},"example":"wix"}],"responses":{"200":{"description":"The business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Business"},"example":{"businessId":"biz-48213","businessName":"Green Valley Lawn Care","status":"in_review","createdAt":"2026-11-10T15:00:04.000Z","updatedAt":"2026-11-10T15:06:12.000Z","integrations":[{"type":"partner-crm","referenceId":"xapp-3f9c2a71","campaignId":"campaign-991"}],"widget":{"widgetId":"wgt_8d21","features":{"chat":true,"form":true},"snippet":"<script id=\"xapp-js\" src=\"https://widget.xapp.ai/xapp-chat-widget.js?key=wgt_8d21\" nitro-exclude defer></script>","instructions":{"platform":"generic","title":"Any website","placement":"Before </body> on every page","markdown":"# Add the website widget to your site\n\nThese steps work for almost any website where you, or your web person, can edit the site's HTML.\n\n## Before you start\n\n- You need access to edit your website's HTML or page template.\n\n## Steps\n\n1. Open the HTML of your website, or the shared template or footer that every page uses.\n\n2. Find the closing `</body>` tag.\n\n3. Paste the code below just before the closing `</body>` tag:\n\n   ```html\n   <script id=\"xapp-js\" src=\"https://widget.xapp.ai/xapp-chat-widget.js?key=wgt_8d21\" nitro-exclude defer></script>\n   ```\n\n   It needs to be on every page where you want the widget to appear. If your site has a shared footer or layout file, paste it there once.\n\n4. Save your changes. If your site is hosted on a server, upload the updated file.\n\n## Check it worked\n\nVisit your website. The widget button should appear on the page. It can take a few minutes to show up; if you don't see it, clear your browser cache or open the site in a private window.\n\n## Troubleshooting\n\n- **Widget not appearing**: make sure the code was pasted exactly as provided, just before `</body>`, and that the change was saved and uploaded.\n- **Only some pages show it**: the code is on those pages only. Add it to the shared template or footer so every page gets it.\n- **Still nothing**: open your browser's developer console and look for script errors on the page.\n","availablePlatforms":["drupal","duda","framer","generic","godaddy","joomla","shopify","squarespace","wix","wordpress","zyro"]},"live":false},"bookOnline":{"status":"pending_google","googlePlaceId":"ChIJN1t_tDeuEmsRUsoyG83frY4"},"bookingLink":"https://book.example/?key=frm_19ce","agent":{"mcpUrl":"https://agentic.xapp.ai/green-valley-lawn-care/mcp","manifestUrl":"https://agentic.xapp.ai/green-valley-lawn-care/.well-known/mcp/manifest.json","serverCardUrl":"https://agentic.xapp.ai/green-valley-lawn-care/mcp/server-card","tags":"<link rel=\"mcp-server\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/mcp\">\n<link rel=\"mcp-manifest\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/.well-known/mcp/manifest.json\">\n<link rel=\"mcp-server-card\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/mcp/server-card\">","instructions":{"platform":"wordpress","title":"WordPress","placement":"Inside <head> on every page","markdown":"# Help AI assistants find your business on WordPress\n\n…\n\n```html\n<link rel=\"mcp-server\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/mcp\">\n<link rel=\"mcp-manifest\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/.well-known/mcp/manifest.json\">\n<link rel=\"mcp-server-card\" href=\"https://agentic.xapp.ai/green-valley-lawn-care/mcp/server-card\">\n```\n\n…","availablePlatforms":["drupal","duda","framer","generic","godaddy","joomla","shopify","squarespace","wix","wordpress","zyro"]}}}}}},"400":{"description":"No business id, or one that is not valid URL encoding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No business with this id for this partner. A business can be read as soon as its setup event is accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}}}}},"/partner/v1/businesses/{businessId}/analytics":{"get":{"operationId":"getBusinessAnalytics","tags":["Businesses"],"summary":"Get a business's analytics","description":"Leads and website traffic for one of the partner's businesses over a window. Without `to`, the window ends now; without `from`, it starts 30 days before `to`. At most 366 days. A business belonging to another partner is a `404`, exactly like one that does not exist. A business not set up yet reports zeros.","parameters":[{"name":"businessId","in":"path","required":true,"description":"The partner's own id for the business, as sent in its events. URL-encode it.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"},"example":"biz-48213"},{"name":"from","in":"query","required":false,"description":"Start of the window, ISO 8601.","schema":{"type":"string","format":"date-time"},"example":"2026-10-01T00:00:00Z"},{"name":"to","in":"query","required":false,"description":"End of the window, ISO 8601.","schema":{"type":"string","format":"date-time"},"example":"2026-11-01T00:00:00Z"}],"responses":{"200":{"description":"The business's analytics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAnalytics"},"example":{"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}}}}},"400":{"description":"A `from` or `to` that cannot be read, a `from` not before `to`, or a window over 366 days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"},"example":{"message":"from must be before to"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No such business for this partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"},"example":{"message":"Business not found"}}}}}}},"/partner/graphql":{"post":{"operationId":"graphql","tags":["GraphQL"],"summary":"Query with GraphQL","description":"The same reads as the REST routes, in one request: the partner, its businesses a page at a time, one business with its install steps for a platform, and each business's analytics. Behind the same partner key. Introspection is on, so GraphQL tools can load the schema from here.\n\n```graphql\nquery {\n  partner {\n    businesses(status: live, first: 25) {\n      businesses {\n        businessId\n        businessName\n        analytics(from: \"2026-10-01T00:00:00Z\", to: \"2026-11-01T00:00:00Z\") {\n          leads { total highValue }\n          traffic { visitors chatOpens submissions { website bookOnline bookingLink } }\n        }\n      }\n      nextCursor\n    }\n  }\n}\n```\n\nOne request can ask for analytics on at most 25 businesses: page with `first: 25` when asking for each business's analytics. A business that does not exist, or is another partner's, is `null`. Bad input (an unknown platform, a bad window or cursor) is an error with `extensions.code` `BAD_USER_INPUT`. The API only reads: a mutation or subscription is refused with `extensions.code` `GRAPHQL_VALIDATION_FAILED`; changes are events.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"variables":{"type":"object","additionalProperties":true},"operationName":{"type":"string"}}},"example":{"query":"query ($id: ID!) { partner { business(businessId: $id) { status analytics { leads { total } } } } }","variables":{"id":"biz-48213"}}}}},"responses":{"200":{"description":"A GraphQL response: `data`, and `errors` when any part failed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","nullable":true},"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"extensions":{"type":"object","properties":{"code":{"type":"string"}}}}}}}},"example":{"data":{"partner":{"business":{"status":"live","analytics":{"leads":{"total":12}}}}}}}}},"400":{"description":"A query that does not parse or does not match the schema.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}},"components":{"securitySchemes":{"PartnerKey":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A partner key issued by XAPP. Send it as `Authorization: Bearer <partner key>`. A partner may hold two keys at once, so it can rotate one without downtime."}},"responses":{"Unauthorized":{"description":"No partner key, a key not sent as `Bearer`, or one that fails verification - including a revoked key."},"Forbidden":{"description":"The key verifies but is not a partner key, or belongs to no organization."}},"schemas":{"Message":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"EventReceipt":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","description":"The event's `id`."},"status":{"type":"string","enum":["accepted","duplicate"]}}},"ValidationError":{"type":"object","required":["message","errors"],"properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string","description":"Dotted path into the body, e.g. `data.integrations[0].type`, or `body` when the body itself is unreadable."},"message":{"type":"string"}}}}}},"EventEnvelope":{"type":"object","description":"Every event has this shape. Fields not listed here are ignored, so adding one never breaks a request.","required":["id","type","version","occurredAt","businessId","data"],"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$","description":"Unique per event, chosen by the sender (a ULID or UUID). Resending the same `id` is a duplicate, never a second change."},"type":{"type":"string","description":"`business.<subject>.<what happened>`; `_requested` for asks."},"version":{"type":"string","description":"Schema version of `data` for this type."},"occurredAt":{"type":"string","format":"date-time","description":"When it happened at the sender, ISO 8601 with a time zone."},"businessId":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$","description":"The partner's own id for the business, the same in every event and query."},"data":{"type":"object"}}},"SetupRequestedEvent":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","enum":["business.setup_requested"]},"version":{"type":"string","enum":["1"]},"data":{"$ref":"#/components/schemas/SetupRequestedData"}}}]},"SetupRequestedData":{"type":"object","required":["businessName"],"description":"Most details (services, hours, the website platform) are read from the business's website and Google profile, so only `businessName` is required.","properties":{"businessName":{"type":"string","minLength":1,"maxLength":256,"description":"As customers should see it."},"website":{"type":"string","format":"uri","maxLength":2048,"description":"Public homepage, `http` or `https`. Without it, no web widget is built."},"googleBusinessProfile":{"type":"string","maxLength":2048,"description":"A Google place id, or a Maps URL that carries one (`query_place_id=` or `place_id:`). Book Online needs a place."},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"E.164, e.g. `+15555550123`."},"streetAddress":{"type":"string","maxLength":2048},"city":{"type":"string","maxLength":2048},"state":{"type":"string","pattern":"^[A-Z]{2}$","description":"Two-letter code, e.g. `TX`."},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","description":"5 digits or ZIP+4."},"timezone":{"type":"string","description":"IANA name, e.g. `America/Chicago`. Otherwise worked out from the address or Google profile."},"integrations":{"type":"array","description":"Integrations to connect the business to, each at most once. The partner's own integration is always connected; name it here only to send its settings. Any other `type` is connected from its `config`. Settings are checked when the event arrives; a 400 lists every problem. A setting the integration itself refuses later (a credential it rejects) leaves the business `failed`, with the reason in `failureReason`.","items":{"$ref":"#/components/schemas/Integration"}},"contact":{"type":"object","description":"The partner's account manager for this business, so XAPP can reach the right person about a setup problem. Never shown to the customer.","properties":{"name":{"type":"string","maxLength":256},"email":{"type":"string","format":"email"}}}}},"LeadCapturedEvent":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","enum":["lead.captured"]},"version":{"type":"string","enum":["1"]},"data":{"$ref":"#/components/schemas/LeadCapturedData"}}}]},"LeadCapturedData":{"type":"object","required":["source","contact"],"properties":{"source":{"$ref":"#/components/schemas/InteractionSource"},"contact":{"allOf":[{"$ref":"#/components/schemas/PartnerContact"}],"description":"Needs at least one of `name`, `firstName`, `lastName`, `phone` or `email`."},"request":{"type":"string","maxLength":4000,"description":"What the person asked for, in their words."},"contactMethod":{"type":"string","enum":["form","phone","chat","email","sms","other"],"default":"form","description":"How the person reached the business."},"agentType":{"type":"string","enum":["ai","human","self_serve","unknown"],"default":"unknown","description":"Who took the lead."},"fields":{"type":"object","maxProperties":30,"additionalProperties":{"type":"string","maxLength":2048},"description":"Anything else the platform captured, as name/value strings."},"deliver":{"type":"boolean","default":false,"description":"Also send it to the business: its lead emails and texts, and its CRM connection. Default `false`: it only appears on the dashboard."}}},"CallCompletedEvent":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","enum":["call.completed"]},"version":{"type":"string","enum":["1"]},"data":{"$ref":"#/components/schemas/CallCompletedData"}}}]},"CallCompletedData":{"type":"object","required":["source","transcript"],"properties":{"source":{"$ref":"#/components/schemas/InteractionSource"},"transcript":{"type":"object","description":"The conversation, as `turns` or as plain `text`. One of the two is required.","properties":{"turns":{"type":"array","maxItems":2000,"items":{"type":"object","required":["speaker","text"],"properties":{"speaker":{"type":"string","enum":["agent","caller","other"]},"text":{"type":"string","maxLength":8192},"at":{"type":"string","format":"date-time"}}}},"text":{"type":"string","maxLength":204800}}},"direction":{"type":"string","enum":["inbound","outbound"]},"durationSeconds":{"type":"number","minimum":0,"maximum":86400},"callerPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"The caller's number from your phone system, E.164. Used as the lead's phone unless `contact.phone` is sent."},"agentType":{"type":"string","enum":["ai","human"],"default":"ai","description":"Who answered."},"recordingUrl":{"type":"string","format":"uri","description":"An https link to the recording. Kept on the lead as a link; XAPP does not fetch it."},"contact":{"allOf":[{"$ref":"#/components/schemas/PartnerContact"}],"description":"What you already know about the caller. Used first; the transcript fills in anything missing."},"deliver":{"type":"boolean","default":false,"description":"Also send it to the business: its lead emails and texts, and its CRM connection. Default `false`: it only appears on the dashboard."}}},"InteractionSource":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","maxLength":64,"description":"Where the lead or call came from, as you name it, e.g. `Facebook Lead Ads`. Shown on the dashboard as the lead's source."}}},"PartnerContact":{"type":"object","description":"The person's details, as you have them. Every field is optional.","properties":{"name":{"type":"string","maxLength":256,"description":"Full name. Or send `firstName` and `lastName`."},"firstName":{"type":"string","maxLength":256},"lastName":{"type":"string","maxLength":256},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"E.164, e.g. `+15555550123`."},"email":{"type":"string","format":"email","maxLength":256},"address":{"type":"object","properties":{"street":{"type":"string","maxLength":256},"city":{"type":"string","maxLength":256},"state":{"type":"string","pattern":"^[A-Z]{2}$"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"}}}}},"Integration":{"type":"object","required":["type"],"properties":{"type":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$","example":"hubspot","description":"Your own integration, as agreed with XAPP when your account was set up, or any integration Studio can add: `surefire`, `servicetitan`, `housecallpro`, `fieldpulse`, `fieldroutes`, `hubspot`, `jobnimbus`, `gohighlevel`, `poolbrain`, `serviceminder`, `contractor-appointments`, `webhook`, `opta`, `leadperfection`, `boberdoo`, `facebook_capi`, `openai_capi`, `ga4`. Paid add-ons (Lead Connect) are bought for a business and cannot be set up here."},"config":{"type":"object","description":"Settings per `type`. Each is the field Studio's form for that integration asks for; `*` is required, (secret) is encrypted on arrival and never stored or returned in the clear.\n\n- Your own integration: the values agreed with XAPP, such as a campaign id in your system. XAPP fills in everything else, including the `referenceId`.\n- `surefire`: `token`* string (secret), `endpoint`* url, `dataMap`* string\n- `servicetitan`: `clientId`* string, `clientSecret`* string (secret), `serviceTitanAppId`* string, `tenantId`* string, `bookingProviderId`* string, `defaultBusinessUnitId`* int, `defaultCampaignId`* int, `defaultJobTypeId`* int, `apiEndpoint`* string, `authEndpoint`* string, `leadImport` boolean, `outcomeTracking` boolean\n- `housecallpro`: `token`* string (secret)\n- `fieldpulse`: `token`* string (secret), `defaultJobTypeId`* string, `maxJobsPerDay`* int, `lookAheadDays`* int\n- `fieldroutes`: `subdomain`* string, `authenticationKey`* string (secret), `authenticationToken`* string (secret), `sourceID` string, `defaultAppointmentType` string\n- `hubspot`: `accessToken`* string (secret), `meetingLinkSlug` string\n- `jobnimbus`: `apiKey`* string (secret), `contactRecordTypeName` string, `contactStatusName` string, `leadSourceName` string, `createJob`* boolean, `jobRecordTypeName` string, `jobStatusName` string, `salesRepJnid` string\n- `gohighlevel`: `privateToken`* string (secret), `locationId`* string, `calendarId` string, `tags` string[]\n- `poolbrain`: `apiKey`* string (secret), `companyId` string, `liveScheduling` boolean, `serviceLevelId` int, `jobTemplateId` int\n- `serviceminder`: `apiKey`* string (secret), `defaultJobTypeId` string\n- `contractor-appointments`: `campaignId`* string, `campaignKey`* string (secret), `defaultTrade` string\n- `webhook`: `endpoint`* url, `httpHeaders` json (secret), `service` string, `fieldMapping` json, `flattenPayload` boolean\n- `opta`: `subdomain`* string, `companyId`* string, `sourceId`* string, `campaignId`* string, `authKey`* string (secret), `test` boolean, `subId1` string, `subId2` string\n- `leadperfection`: `clientId`* string, `srsId`* string, `sender` string, `defaultProductId` string, `rankId` string, `proId` string\n- `boberdoo`: `endpoint`* url, `apiKey`* string (secret), `source`* string, `leadType`* string, `apiAction` string, `mode` string, `defaultProject` string, `defaultLandingPage` string, `uniqueIdentifier` string, `omitAppointmentInComments` boolean\n- `facebook_capi`: `pixelId`* string, `accessToken`* string (secret), `testEventCode` string\n- `openai_capi`: `pixelId`* string, `accessToken`* string (secret)\n- `ga4`: `measurementId`* string, `apiSecret`* string (secret)","additionalProperties":true}}},"Business":{"type":"object","required":["businessId","businessName","status","createdAt","updatedAt","integrations"],"properties":{"businessId":{"type":"string"},"businessName":{"type":"string"},"status":{"type":"string","enum":["provisioning","in_review","google_pending","live","stopped","failed"],"description":"`provisioning` → `in_review` → `google_pending` → `live`. A business can move to `failed` or `stopped` from any of them. On `failed`, XAPP contacts the partner."},"failureReason":{"type":"string","description":"Only when `status` is `failed`: why, and what to do about it. Fix the cause, then send the setup event again with a new `id`."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"integrations":{"type":"array","description":"Every integration the business is connected to. Empty until setup has built the business. Settings are never returned.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"referenceId":{"type":"string","description":"Identifies the business to that lead destination. Created by XAPP."},"campaignId":{"type":"string"}}}},"widget":{"type":"object","description":"The web widget, which handles chat and forms. Absent until built, or without a website.","required":["widgetId","features","snippet","instructions","live"],"properties":{"widgetId":{"type":"string"},"features":{"type":"object","properties":{"chat":{"type":"boolean"},"form":{"type":"boolean"}}},"snippet":{"type":"string","description":"The tag to install once on every page."},"instructions":{"type":"object","properties":{"platform":{"type":"string","description":"The platform the steps are for: the `platform` asked for, or `generic`."},"title":{"type":"string","description":"The platform's name, e.g. `Wix`."},"placement":{"type":"string","description":"Where the snippet goes on the page."},"markdown":{"type":"string","description":"The steps in plain Markdown, with the snippet already in them. No branding and no links."},"availablePlatforms":{"type":"array","items":{"type":"string"},"description":"Every platform there are steps for; ask for one with `?platform=`."}},"description":"White-label steps for installing the widget, written to be sent on as they are, for example in an email to the business.","required":["platform","title","placement","markdown","availablePlatforms"]},"live":{"type":"boolean","description":"Whether the widget has loaded on a live page. Always `false` until load detection ships."}}},"bookOnline":{"type":"object","description":"Absent without a Google place.","required":["status","googlePlaceId"],"properties":{"status":{"type":"string","enum":["pending_google","live"]},"googlePlaceId":{"type":"string"}}},"bookingLink":{"type":"string","format":"uri","description":"A booking page that works anywhere: email, social, text messages, a button on the site."},"agent":{"type":"object","description":"The business's public MCP server for AI agents. Absent until the business is built. The installed widget advertises these in the page's `<head>` (`<link rel=\"mcp-server\">`, `mcp-manifest` and `mcp-server-card`), so an AI agent browsing the business's site can find the server and use it instead of scraping the page.","required":["mcpUrl","manifestUrl","serverCardUrl","tags"],"properties":{"mcpUrl":{"type":"string","format":"uri","description":"The MCP server: Streamable HTTP, no sign-in. Its tools give the business's profile, answer questions from its content, and take a lead, which is delivered like any other."},"manifestUrl":{"type":"string","format":"uri","description":"The MCP manifest."},"serverCardUrl":{"type":"string","format":"uri","description":"The MCP server card."},"tags":{"type":"string","description":"The three discovery tags for the page's `<head>`, one per line, ready to paste. The widget adds them too; in the header they also reach agents that don't run scripts. Having both is harmless: the widget leaves tags the page already has."},"instructions":{"type":"object","properties":{"platform":{"type":"string","description":"The platform the steps are for: the `platform` asked for, or `generic`."},"title":{"type":"string","description":"The platform's name, e.g. `Wix`."},"placement":{"type":"string","description":"Where the tags go: inside `<head>` on every page, or that no placement is needed on a platform with nowhere to put header code (GoDaddy Website Builder), where the widget adds them itself."},"markdown":{"type":"string","description":"The steps in plain Markdown, with the snippet already in them. No branding and no links."},"availablePlatforms":{"type":"array","items":{"type":"string"},"description":"Every platform there are steps for; ask for one with `?platform=`."}},"description":"White-label steps for adding the tags to the platform's page header, the tags already in them, to send on as they are. For the `platform` asked for, else the generic steps. Left out of `GET /partner/v1/businesses`.","required":["platform","title","placement","markdown","availablePlatforms"]}}}}},"BusinessPage":{"type":"object","required":["businesses"],"properties":{"businesses":{"type":"array","description":"Each as `Business`, without `widget.instructions`.","items":{"$ref":"#/components/schemas/Business"}},"nextCursor":{"type":"string","description":"Pass back as `cursor` for the next page. Absent on the last page."}}},"ChannelCounts":{"type":"object","required":["website","bookOnline","bookingLink"],"description":"`website`: the business's own site; `bookOnline`: Reserve with Google; `bookingLink`: the booking page link.","properties":{"website":{"type":"integer"},"bookOnline":{"type":"integer"},"bookingLink":{"type":"integer"}}},"BusinessAnalytics":{"type":"object","required":["businessId","from","to","leads","traffic","agents"],"properties":{"businessId":{"type":"string"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"leads":{"type":"object","required":["total","highValue"],"properties":{"total":{"type":"integer","description":"Leads received in the window. Test and abandoned leads are left out."},"highValue":{"type":"integer","description":"Of those, leads classified as high value."}}},"traffic":{"type":"object","required":["visitors","uniqueVisitors","pageViews","chatOpens","sessions","submissions","sources"],"properties":{"visitors":{"type":"integer","nullable":true,"description":"Visitors to the business's own website, counted by IP address. Bots and crawlers are left out. Null when it could not be read, so an outage never reads as no visitors."},"uniqueVisitors":{"type":"integer","nullable":true,"description":"Distinct browsers on the business's own website. Null before the widget recorded them."},"pageViews":{"type":"integer","nullable":true,"description":"Page views on the business's own website. Null before the widget recorded them."},"chatOpens":{"type":"integer","description":"Chat windows opened."},"sessions":{"allOf":[{"$ref":"#/components/schemas/ChannelCounts"}],"description":"Sessions per channel."},"submissions":{"allOf":[{"$ref":"#/components/schemas/ChannelCounts"}],"description":"Booking-form submissions per channel."},"sources":{"type":"array","description":"Arrivals on the business's own website per traffic channel, largest first. Channels with none are left out.","items":{"type":"object","required":["channel","sessions"],"properties":{"channel":{"type":"string","enum":["google_search","google_maps","facebook","instagram","other_social","ai","other_search","email","referral","direct"]},"sessions":{"type":"integer"}}}}}},"agents":{"type":"object","nullable":true,"description":"AI agents and crawlers on the business's site, and the people AI assistants sent there. Null when it could not be read, so an outage never reads as no agents.","required":["visitors","formSubmits","byAgent","aiReferrals","crawlers"],"properties":{"visitors":{"type":"integer","description":"Distinct AI agents browsing for someone (ChatGPT agent, Claude, …) that loaded the widget."},"formSubmits":{"type":"integer","description":"Of those, how many submitted a form."},"byAgent":{"type":"array","description":"Those agents by name, most visitors first.","items":{"type":"object","required":["name","visitors","formSubmits"],"properties":{"name":{"type":"string","example":"ChatGPT-User"},"visitors":{"type":"integer"},"formSubmits":{"type":"integer"}}}},"aiReferrals":{"type":"array","description":"People an AI assistant sent to the site, by assistant (`chatgpt`, `perplexity`, `google-ai-overview`, …), most first.","items":{"type":"object","required":["name","visitors"],"properties":{"name":{"type":"string"},"visitors":{"type":"integer"}}}},"crawlers":{"type":"integer","description":"Distinct search and other crawlers."}}}}}}}}