Visitors

Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.

List visitors, most recently seen first

GET /visitors

Scope: visitors:read. Operation id: listVisitors.

Parameters

Name	In	Type	Meaning
`limit`	query	integer	Page size, 1 to 200. Default 50.
`cursor`	query	string	The `nextCursor` from the previous page. Opaque; never build one.
`identified`	query	boolean	`true` keeps only visitors with an email or a CRM contact.
`email`	query	string (email)	Exact match, case-insensitive.

Example request

curl "https://api.showpilot.com/v1/visitors?limit=50" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

One page of visitors.

Field	Type	Always	Meaning
`items`	array of Visitor	yes
`nextCursor`	NextCursor	yes

Visitor

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`email`	string or null	yes
`displayName`	string or null	yes
`status`	string	yes	The agent's read of where the visitor is.
`intentScore`	integer	yes	0 to 100.
`visitCount`	integer	yes
`firstSeenAt`	string (date-time)	yes
`lastSeenAt`	string (date-time)	yes
`account`	object or null	yes	The company the visitor appears to belong to, when known.
`crm`	object or null	yes	The CRM contact this visitor is linked to, when one is.
`labels`	object	yes	The latest labels the agent assigned, by name.

NextCursor

Pass as cursor for the next page; null on the last page.

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

One visitor with their journey

GET /visitors/{id}

Scope: visitors:read. Operation id: getVisitor.

The visitor plus the last 20 conversations, the last 20 tour sittings, the lead record if one exists, and open follow-ups.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)	The visitor's UUID.

Example request

curl "https://api.showpilot.com/v1/visitors/b0000001-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The visitor and their journey.

Every field of Visitor, plus:

Field	Type	Always	Meaning
`journey`	VisitorJourney	yes

Visitor

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`email`	string or null	yes
`displayName`	string or null	yes
`status`	string	yes	The agent's read of where the visitor is.
`intentScore`	integer	yes	0 to 100.
`visitCount`	integer	yes
`firstSeenAt`	string (date-time)	yes
`lastSeenAt`	string (date-time)	yes
`account`	object or null	yes	The company the visitor appears to belong to, when known.
`crm`	object or null	yes	The CRM contact this visitor is linked to, when one is.
`labels`	object	yes	The latest labels the agent assigned, by name.

VisitorJourney

Field	Type	Always
`conversations`	array of Conversation	yes
`sittings`	array of Sitting	yes
`lead`	object	yes
`openFollowUps`	array of FollowUp	yes

Conversation

Field	Type	Always
`id`	string (uuid)	yes
`agentId`	string (uuid)	yes
`visitorId`	string or null (uuid)	yes
`channel`	`chat` · `voice`	yes
`pageUrl`	string or null (uri)	yes
`referrer`	string or null	yes
`startedAt`	string (date-time)	yes
`lastMessageAt`	string or null (date-time)	yes
`endedAt`	string or null (date-time)	yes

Sitting

One play of a tour by one viewer.

Field	Type	Always	Meaning
`id`	string	yes	The view session id.
`tourId`	string (uuid)	yes
`visitorId`	string or null	yes
`email`	string or null	yes
`source`	string or null	yes	Where it played: `preview`, `lightbox`, `embed`, `share`, `chat` or `legacy`.
`startedAt`	string (date-time)	yes
`endedAt`	string (date-time)	yes
`seconds`	integer	yes
`stepViews`	integer	yes	Step views including revisits.
`stepsSeen`	array of integer	yes	Distinct step indexes
`maxStep`	integer	yes	Furthest step index reached; -1 when none.
`completed`	boolean	yes
`ctaClicks`	integer	yes

FollowUp

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`agentId`	string or null (uuid)	yes
`conversationId`	string or null (uuid)	yes
`visitorId`	string or null (uuid)	yes
`question`	string	yes	The visitor's question
`reason`	string or null	yes
`status`	`open` · `answered` · `dismissed`	yes
`answer`	string or null	yes
`answeredAt`	string or null (date-time)	yes
`deliveredAt`	string or null (date-time)	yes	When the agent delivered the answer to the visitor.
`createdAt`	string (date-time)	yes

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Find visitors by what they asked

POST /visitors/search

Scope: visitors:read. Operation id: searchVisitors.

Free text over what each visitor asked and said — their chat turns, the questions the agent escalated, its own summaries, qualifying answers — plus the structured facts. The same match a saved segment runs, returning the people rather than a count, and saving nothing. asked takes web-search syntax: security OR SOC2, "single sign-on", pricing -enterprise.

Example request

curl "https://api.showpilot.com/v1/visitors/search" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The matching visitors, most recently seen first.

Field	Type	Always	Meaning
`count`	integer	yes	How many matched in total
`truncated`	boolean	yes	True when more matched than were returned.
`filter`	SegmentFilter	yes
`items`	array of Visitor	yes

SegmentFilter

Conditions AND together. At least one is required.

Field	Type	Always	Meaning
`asked`	string	no	Web-search syntax over what the visitor asked and said: `security OR SOC2`, `"single sign-on"`, `pricing -enterprise`.
`toursWatched`	array of string (uuid)	no	Any of these tours was watched.
`identified`	boolean	no	Has an email or a CRM contact.
`hasCrm`	boolean	no
`minIntent`	integer	no
`lastSeenWithinDays`	integer	no
`qualified`	object	no	Qualifying answers that must equal these values.
`labels`	object	no
`account`	object	no

Visitor

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`email`	string or null	yes
`displayName`	string or null	yes
`status`	string	yes	The agent's read of where the visitor is.
`intentScore`	integer	yes	0 to 100.
`visitCount`	integer	yes
`firstSeenAt`	string (date-time)	yes
`lastSeenAt`	string (date-time)	yes
`account`	object or null	yes	The company the visitor appears to belong to, when known.
`crm`	object or null	yes	The CRM contact this visitor is linked to, when one is.
`labels`	object	yes	The latest labels the agent assigned, by name.

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

One company, the people, and what they asked

GET /accounts/{domain}

Scope: visitors:read. Operation id: getAccountBrief.

The company card — CRM stage, owner, open deals, tier — with the people from it, strongest intent first, and the questions they left unanswered. Matched on the ENRICHED domain, so a brief works for a company whose visitors have never filled in a form. The questions are the visitor's own words, so they are masked unless the key holds conversations:transcripts.

Parameters

Name	In	Type	Meaning
`domain`	path	string	A hostname. A scheme, `www.` and a path are all stripped.

Example request

curl "https://api.showpilot.com/v1/accounts/acme.com" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The brief. account is null when nothing from this company has been seen.

AccountBrief

Field	Type	Always	Meaning
`domain`	string	yes
`account`	object	yes
`peopleCount`	integer	yes	People from this company in total
`topIntent`	integer	yes
`lastSeenAt`	string or null (date-time)	yes
`people`	array of Visitor	yes
`openQuestions`	array of object	yes	What they asked that the agent could not answer — the opening line for a call.
`redaction`	object	yes

Visitor

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`email`	string or null	yes
`displayName`	string or null	yes
`status`	string	yes	The agent's read of where the visitor is.
`intentScore`	integer	yes	0 to 100.
`visitCount`	integer	yes
`firstSeenAt`	string (date-time)	yes
`lastSeenAt`	string (date-time)	yes
`account`	object or null	yes	The company the visitor appears to belong to, when known.
`crm`	object or null	yes	The CRM contact this visitor is linked to, when one is.
`labels`	object	yes	The latest labels the agent assigned, by name.

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

On this page