# SPOTIO

> SPOTIO is a field sales engagement and territory management platform for outside sales teams. Behind the mobile app and web console is a 295-operation REST API (SPOTIO 2.0), a signed outbound webhook system, and a first-party remote MCP server. This file was generated by API Evangelist from SPOTIO's own published contract and documentation; SPOTIO serves no llms.txt of its own (https://spotio.com/llms.txt and https://developer.spotio2.com/llms.txt both return 404, probed 2026-08-13).

The one thing to understand before writing any code: SPOTIO has no fixed Lead entity. It has a polymorphic DataObject whose type, stages and every field are defined per tenant in a Workflow, and writes address fields by numeric `fieldId`. Read the workflow first (`GET /api/workflow/dataObjects/full`), then write.

- Base URL: https://api.spotio2.com
- Test host: https://app-test.spotio2.com
- Auth: `Authorization: Bearer <token>`; mint with `POST /api/users/apitoken` using a clientId + secret created in the web app under Settings -> Integrations -> API Access. Tokens expire after 30 days.
- Pagination: cursor. Repeat with the returned `scrollId` until it is null. Stages, Custom Fields, Activity Templates and Users are never paginated.
- Errors: `{"errors": {"<field>": "<message>"}}`. Not RFC 9457. Entity-level errors are keyed `_`.
- Idempotency: none published. Retries are not replay-safe.
- Rate limits: none published. No 429 is declared on any operation and no Retry-After is documented.

## Docs

- [Quickstart](https://developer.spotio2.com/docs/spotio2/a4cpj8d1knctg-quickstart-for-the-spotio-api): curl your first token and first request
- [Introduction](https://developer.spotio2.com/docs/spotio2/qu2ht3gipl905-introduction): JSON-only, ISO-8601, camelCase enums, PUT-is-complete-resource
- [Authenticating](https://developer.spotio2.com/docs/spotio2/3f682d2s8ezln-authenticating-to-the-rest-api): token minting, 30-day expiry, key inherits the creating user's role
- [Paginating and Sorting](https://developer.spotio2.com/docs/spotio2/o5nz1a7nbyivu-paginating-and-sorting): scrollId, perPage, totalCount
- [Status Codes and Errors](https://developer.spotio2.com/docs/spotio2/8l7aj7gsg81ix-status-codes-and-errors): the errors envelope and fieldTempId echo
- [Filtering Collections](https://developer.spotio2.com/docs/spotio2/a56edkm4m96ez-filtering-collections): persist a filter, then pass filterId
- [Working with DataObjects](https://developer.spotio2.com/docs/spotio2/6b9e62ga3clm5-working-with-data-objects): the workflow structure
- [Creating DataObjects](https://developer.spotio2.com/docs/spotio2/s12ejhvxsb6hf-creating-data-objects): required fields, defaults, fieldId resolution
- [Working with Exports](https://developer.spotio2.com/docs/spotio2/e8leh9956dljs-working-with-exports): submit then poll until state is ready
- [Working With Bulk Jobs](https://developer.spotio2.com/docs/spotio2/8zeggtfnhfk9t-working-with-bulk-jobs): NDJSON batch lifecycle
- [Webhooks](https://support.spotio.com/hc/en-us/articles/360057063834-Webhooks): 10 events, X-Signature HMAC-SHA256, 3 retries, 10s timeout
- [Configuring Data Objects](https://support.spotio.com/hc/en-us/articles/11712242070807-Configuring-Data-Objects): the admin side of the workflow model

## Specs

- [SPOTIO 2.0 OpenAPI (source, 3.0.1)](https://api.stoplight.io/projects/cHJqOjIzMTU4MQ/branches/main/export/spotio-swagger.json): 238 paths, 295 operations, 510 schemas. Note: no operationIds.
- Refined per-capability OpenAPI 3.2.0 documents: 39 files under `openapi/` in the API Evangelist repo, one per capability tag.

## Agent surfaces

- MCP server (remote): https://app.spotio2.com/mcp - authenticate with a `SPOTIO-MCP-KEY` header or `?mcpkey=`. Mint the key with `POST /api/Mcp/keys/generate`, read it with `GET /api/Mcp/keys/current`, rotate with `PUT /api/Mcp/keys/regenerate`, revoke with `DELETE /api/Mcp/keys/current`. `tools/list` is auth-gated, so the tool set is not publicly enumerable.
- A2A agent card: none. `/.well-known/agent-card.json` and `/.well-known/agent.json` return 404/403 on all five SPOTIO hosts.
- Mock server: https://stoplight.io/mocks/spotio/spotio2/264959918 - SPOTIO's own Prism mock, answers anonymously as long as any Authorization bearer header is present.

## Capabilities

- DataObjects (25 ops) - the polymorphic core record; create, read, update, search, merge
- Workflow (35 ops across WorkflowSettings, WorkflowDataObjects, WorkflowStages, WorkflowFields, WorkflowActivityTemplates) - the tenant schema
- Users (16) and Teams (10) - reps, roles, hierarchy
- BusinessCards (14) - the surface the quickstart uses
- ActivitiesV2 (12) - visits, calls, notes, stage changes
- Communication (12) + CommunicationTemplates (11) + MultiChannelCommunication (1) - calls, texts, email
- TripsV2 (11) + Trips (7) + RoutesV2 (8) - route planning and executed trips
- MyReports (10) + Reports (6) + Leaderboards (4) - reporting
- Documents (9), Layouts (9), Contracts (8), Connectors (8)
- DataObjectsBulkJobs (9) - NDJSON batch ingest
- AppointmentsV2 (7) - field appointments
- Filters (7) + FiltersV2 (4) - persisted query objects
- PinsV2 (6) - geocoded locations
- WorkflowStages (6), GenerateContent (6)
- Territories (5) - boundaries, assignment, GeoJSON export
- Exports (5) - asynchronous CSV
- Autoplays (5) - outreach sequences
- UserTracking (5) - rep location
- DataObjectsSearch (5) - full-text search with scrollId
- Webhooks (5) - subscription management
- Mcp (4) - MCP key lifecycle
- NotificationsV2 (3), CalendarSettings (2), UploadCare (1)

## Operations

- Commercial: SPOTIO publishes plan names (B2B, B2C, Custom) but no prices - https://spotio.com/plans/
- Status: https://status.spotio2.com/ (client-rendered; no JSON API, no RSS)
- Release notes: https://support.spotio.com/release-notes (product-level, undated, no API changelog)
- Security and compliance: https://spotio.com/features/security-compliance/ (SOC 2 Type II, GDPR, Azure US/EU, TLS 1.2+, 99.9% uptime)
- Support: support@spotio.com | https://support.spotio.com/
- Integrations: https://spotio.com/integrations/
- No published SDK in any language, no CLI, no Postman collection, no security.txt, no vulnerability disclosure programme.

## Known gaps an agent should plan around

- No operationIds in the spec - bind tools to METHOD + path.
- No idempotency contract - do not blind-retry writes.
- No rate-limit headers and no 429 - back off on latency, not on a signal.
- No AsyncAPI - the 10 webhook events are prose-only, and per-event payload schemas are not published.
- Webhook scope vocabulary is only readable from an authenticated `GET /api/Webhooks/scopes`.
- The status page cannot be read programmatically.