Skip to content
Swingback, home

API reference

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):

Terminal
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..."
Download the OpenAPI specJSON

List a post's votes#

GET/v1/workspaces/{workspace_id}/posts/{post_id}/votes

Any API key: Read or Read and write

Returns the post's votes, newest first.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

Query parameters

  • limitinteger

    How many items to return in the page.

    From 1 to 100Defaults to 25

  • cursorstring

    The previous page's next_cursor, to get the next page.

    At most 1,024 characters

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/votes"
Response · 200 OK
{
  "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#

POST/v1/workspaces/{workspace_id}/posts/{post_id}/votes

An 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_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

Headers

  • Idempotency-Keystring

    Makes 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/jsonrequired
  • end_userobjectrequired

    Who votes: an existing end user by id, or a customer by external_id or email, who's created if new.

    Child fields (5)
    • idstring

      An existing end user's id. Send it alone, without the other fields.

      Starts with user_

    • external_idstring

      The customer's id in your system. Swingback looks for the customer by it first.

      1 to 255 characters

    • emailstring · email

      The customer's email. Without a match on external_id, Swingback looks for the customer by email.

      At most 254 characters

    • namestring

      The customer's name, which replaces the one Swingback has.

      1 to 100 characters

    • avatar_urlstring · URL

      The address of the customer's avatar, http or https, which replaces the one Swingback has.

      At most 2,048 characters

Responses

Example

Request
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"
Response · 201 Created
{
  "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#

DELETE/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_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

  • vote_idstringrequired

    The vote's id.

    Starts with vote_

Responses

  • 204
    No ContentThe vote was deleted.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
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

  • idstring

    Starts with vote_

  • end_userobject

    An end user object.

  • post_idstring

    Starts with post_

  • sourcestring

    Where 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) or import (an import).

    One ofdashboardapiportalimport
  • created_atstring · date-time

Example

The vote object
{
  "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"
}

Search pages, sections and code: a setting, an event, a method.