Follow-ups

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

List follow-ups, newest first

GET /follow-ups

Scope: follow_ups:read. Operation id: listFollowUps.

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.
`status`	query	`open` · `answered` · `dismissed`
`visitorId`	query	string (uuid)

Example request

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

Runs against your sandbox with a test key.

Response

One page of follow-ups.

Field	Type	Always	Meaning
`items`	array of FollowUp	yes
`nextCursor`	NextCursor	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

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 follow-up

GET /follow-ups/{id}

Scope: follow_ups:read. Operation id: getFollowUp.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)

Example request

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

Runs against your sandbox with a test key.

Response

The follow-up.

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.

Answer an open follow-up

POST /follow-ups/{id}/answer

Scope: follow_ups:write. Operation id: answerFollowUp.

Closes the task with the answer. When the visitor left an email and a rep's mailbox is connected, the answer is emailed from that mailbox; otherwise the agent delivers it in the visitor's next conversation. The same path the dashboard queue uses. Requires Idempotency-Key.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/follow-ups/e0000001-0000-4000-8000-000000000000/answer" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The follow-up, now answered, with whether the visitor was emailed.

Every field of FollowUp, plus:

Field	Type	Always	Meaning
`emailed`	boolean	yes
`skipReason`	string or null	yes	`no-email` or `no-mailbox` when not emailed; null when it was.

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
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`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Dismiss an open follow-up

POST /follow-ups/{id}/dismiss

Scope: follow_ups:write. Operation id: dismissFollowUp.

Closes the task without an answer. Requires Idempotency-Key.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/follow-ups/e0000001-0000-4000-8000-000000000000/dismiss" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The follow-up, now dismissed.

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
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`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

On this page