Votes
A vote counts one end user's support for a post, and each end user votes for a post once. Vote on behalf of your customers to bring in the requests your support or sales team hears.
The examples read your API key and your workspace's base URL from two shell variables. Set them once, with your workspace's id in place of ws_... (API keys says where to find both):
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..." List a post's votes#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ votesAny API key: Read or Read and write
Returns the post's votes, newest first.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Query parameters
limitintegerHow many items to return in the page.
From 1 to 100Defaults to
25cursorstringThe previous page's
next_cursor, to get the next page.At most 1,024 characters
Responses
- 200OKA page of votes. The vote objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/votes" {
"data": [
{
"id": "vote_01h455vb4pex5vsknk084sn02q",
"end_user": {
"id": "user_01h455vb4pex5vsknk084sn04s",
"avatar_url": null,
"companies": [
{
"id": "company_01h455vb4pex5vsknk084sn02q",
"external_id": "acme",
"name": "Acme",
"value": 120000
}
],
"email": "lee@example.com",
"external_id": "u-9031",
"kind": "user",
"name": "Lee Park",
"traits": {
"plan": "enterprise"
},
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"banned_at": null,
"email_verified_at": null,
"erased_at": null
},
"post_id": "post_01h455vb4pex5vsknk084sn02q",
"source": "api",
"created_at": "2026-09-28T14:03:12.482Z"
}
],
"next_cursor": null,
"has_more": false
}Create a vote#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ votesAn API key with Read and write access
Adds a vote to the post. With an API key, end_user is required: it names the customer who votes, who is created if new. The voter follows the post, unless they unfollowed it before. If the end user already voted for the post, returns their existing vote with 200.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Headers
Idempotency-KeystringMakes a retry safe: for 24 hours, the same request with the same key returns the first response instead of repeating the change. Use 1 to 255 visible ASCII characters, without spaces, such as a UUID. See Idempotency.
1 to 255 characters
Request body
application/jsonrequiredend_userobjectrequiredWho votes: an existing end user by
id, or a customer byexternal_idoremail, who's created if new.Child fields (5)
idstringAn existing end user's id. Send it alone, without the other fields.
Starts with
user_external_idstringThe customer's id in your system. Swingback looks for the customer by it first.
1 to 255 characters
emailstring · emailThe customer's email. Without a match on
external_id, Swingback looks for the customer by email.At most 254 characters
namestringThe customer's name, which replaces the one Swingback has.
1 to 100 characters
avatar_urlstring · URLThe address of the customer's avatar,
httporhttps, which replaces the one Swingback has.At most 2,048 characters
Responses
- 200OKThe end user's existing vote object.
- 201CreatedThe new vote object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"end_user": {
"external_id": "u-9031",
"email": "lee@example.com",
"name": "Lee Park"
}
}' \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/votes" {
"id": "vote_01h455vb4pex5vsknk084sn02q",
"end_user": {
"id": "user_01h455vb4pex5vsknk084sn04s",
"avatar_url": null,
"companies": [],
"email": "lee@example.com",
"external_id": "u-9031",
"kind": "user",
"name": "Lee Park",
"traits": {},
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"banned_at": null,
"email_verified_at": null,
"erased_at": null
},
"post_id": "post_01h455vb4pex5vsknk084sn02q",
"source": "api",
"created_at": "2026-09-28T14:03:12.482Z"
}Delete a vote#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ votes/ {vote_id}An API key with Read and write access
Removes the vote from the post.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_vote_idstringrequiredThe vote's id.
Starts with
vote_
Responses
- 204No ContentThe vote was deleted.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X DELETE \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/votes/vote_01h455vb4pex5vsknk084sn02q" The response is 204 No Content, with no body.
The vote object#
Fields
idstringStarts with
vote_end_userobjectAn end user object.
post_idstringStarts with
post_sourcestringWhere the vote came from:
dashboard(a teammate added it in the dashboard, for themselves or a customer),api(an API key),portal(the end user voted on the portal or in the widget) orimport(an import).One ofdashboardapiportalimportcreated_atstring · date-time
Example
{
"id": "vote_01h455vb4pex5vsknk084sn02q",
"end_user": {
"id": "user_01h455vb4pex5vsknk084sn04s",
"avatar_url": null,
"companies": [
{
"id": "company_01h455vb4pex5vsknk084sn02q",
"external_id": "acme",
"name": "Acme",
"value": 120000
}
],
"email": "lee@example.com",
"external_id": "u-9031",
"kind": "user",
"name": "Lee Park",
"traits": {
"plan": "enterprise"
},
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"banned_at": null,
"email_verified_at": null,
"erased_at": null
},
"post_id": "post_01h455vb4pex5vsknk084sn02q",
"source": "api",
"created_at": "2026-09-28T14:03:12.482Z"
}