Skip to content
Swingback, home

API reference

End users

End users are the people who give feedback: customers (kind is user), whom you find by their id in your system (external_id) or by email; the team's own rows, such as members acting as themselves (team); and guests (guest). Customers have typed traits and belong to companies. Erasing an end user clears their personal data and keeps what they wrote and voted for, anonymously.

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 end users#

GET/v1/workspaces/{workspace_id}/end-users

Any API key: Read or Read and write

Returns the workspace's end users, newest first.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

Query parameters

  • qstring

    Matches part of the name, the email or the external id, ignoring case.

    1 to 100 characters

  • company_idstring

    Only the members of this company.

    Starts with company_

  • 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 "$SWINGBACK_API/end-users?q=dana" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"
Response · 200 OK
{
  "data": [
    {
      "id": "user_01h455vb4pex5vsknk084sn02q",
      "avatar_url": null,
      "companies": [
        {
          "id": "company_01h455vb4pex5vsknk084sn02q",
          "external_id": "acme",
          "name": "Acme",
          "value": 120000
        }
      ],
      "email": "dana@example.com",
      "external_id": "u-8412",
      "kind": "user",
      "name": "Dana Kim",
      "traits": {
        "plan": "enterprise",
        "seats": 40
      },
      "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
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Create or update an end user#

POST/v1/workspaces/{workspace_id}/end-users

An API key with Read and write access

Finds the customer by external_id, else by email, and updates the fields you send. If there's no match, creates the customer, with its traits and companies. An email that belongs to another customer returns 409 end_user_conflict. A trait value whose type doesn't match the trait's definition returns 400.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

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

A customer, found by external_id, else by email. One of the two is required.

  • 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

  • companiesarray of objects

    All of the customer's companies, each created or updated by its external_id. The customer leaves any company that isn't in the list. Omit the field to keep their current companies.

    At most 20 items

    Fields of each item (5)
    • external_idstringrequired

      The company's id in your system, which finds it.

      1 to 255 characters

    • namestring

      The company's name.

      1 to 200 characters

    • domainstring

      The company's domain, such as acme.com, stored in lowercase.

      1 to 253 characters

    • traitsobject

      Traits to set, by key. A key is a letter followed by up to 63 letters, digits or underscores. A value is a string (up to 256 characters), a number or a boolean, and null removes the trait. The first value sent for a new key defines its type, and later values must have that type. A date trait (see Define a trait) takes 2026-09-28 or an RFC 3339 time. Traits you don't send stay as they are.

      At most 50 keysEach value is a string, number or boolean, or null

    • valueinteger

      What the company is worth to you, such as its monthly revenue in cents. A post's customer_value adds up the values of its voters' companies.

      At least 0

  • traitsobject

    Traits to set, by key. A key is a letter followed by up to 63 letters, digits or underscores. A value is a string (up to 256 characters), a number or a boolean, and null removes the trait. The first value sent for a new key defines its type, and later values must have that type. A date trait (see Define a trait) takes 2026-09-28 or an RFC 3339 time. Traits you don't send stay as they are.

    At most 50 keysEach value is a string, number or boolean, or null

Responses

  • 200
    OKThe existing customer, updated. Returns an end user object.
  • 201
    CreatedThe new customer. Returns an end user object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X POST "$SWINGBACK_API/end-users" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "u-8412",
    "email": "dana@example.com",
    "name": "Dana Kim",
    "traits": {
      "plan": "enterprise",
      "seats": 40
    },
    "companies": [
      {
        "external_id": "acme",
        "name": "Acme",
        "value": 120000
      }
    ]
  }'
Response · 200 OK
{
  "id": "user_01h455vb4pex5vsknk084sn02q",
  "avatar_url": null,
  "companies": [
    {
      "id": "company_01h455vb4pex5vsknk084sn02q",
      "external_id": "acme",
      "name": "Acme",
      "value": 120000
    }
  ],
  "email": "dana@example.com",
  "external_id": "u-8412",
  "kind": "user",
  "name": "Dana Kim",
  "traits": {
    "plan": "enterprise",
    "seats": 40
  },
  "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
}

Retrieve an end user#

GET/v1/workspaces/{workspace_id}/end-users/{end_user_id}

Any API key: Read or Read and write

Returns an end user of any kind, banned or erased ones included.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • end_user_idstringrequired

    The end user's id.

    Starts with user_

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/end-users/user_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "id": "user_01h455vb4pex5vsknk084sn02q",
  "avatar_url": null,
  "companies": [
    {
      "id": "company_01h455vb4pex5vsknk084sn02q",
      "external_id": "acme",
      "name": "Acme",
      "value": 120000
    }
  ],
  "email": "dana@example.com",
  "external_id": "u-8412",
  "kind": "user",
  "name": "Dana Kim",
  "traits": {
    "plan": "enterprise",
    "seats": 40
  },
  "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
}

Erase an end user's personal data#

DELETE/v1/workspaces/{workspace_id}/end-users/{end_user_id}

An API key with Read and write access

Clears the email, name, avatar, external id and traits of a customer or a guest, and deletes their sessions, sign-in identities, follows, company memberships, notifications, email preferences, pending emails and Slack links. What they wrote, voted for and liked stays, anonymously. A team member's end user returns 422 cannot_erase_team: remove the member from the team instead. Erasing an end user again changes nothing.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • end_user_idstringrequired

    The end user's id.

    Starts with user_

Responses

Example

Request
curl -X DELETE \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/end-users/user_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "id": "user_01h455vb4pex5vsknk084sn02q",
  "avatar_url": null,
  "companies": [],
  "email": null,
  "external_id": null,
  "kind": "user",
  "name": null,
  "traits": {},
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "banned_at": null,
  "email_verified_at": null,
  "erased_at": "2026-10-02T09:30:00.000Z"
}

Export an end user's data#

GET/v1/workspaces/{workspace_id}/end-users/{end_user_id}/export

Any API key: Read or Read and write

Returns what Swingback keeps about an end user, for a data subject access request: their profile, traits and companies; what they wrote, voted for and liked; their follows, notifications and email preferences; and their sessions and sign-in methods.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • end_user_idstringrequired

    The end user's id.

    Starts with user_

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/end-users/user_01h455vb4pex5vsknk084sn02q/export"
Response · 200 OK
{
  "comments": [
    {
      "id": "comment_01h455vb4pex5vsknk084sn02q",
      "body_md": "We need this for quarterly reports too.",
      "moderation_state": "approved",
      "parent_id": null,
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "visibility": "public",
      "created_at": "2026-09-28T14:03:12.482Z",
      "deleted_at": null
    }
  ],
  "companies": [
    {
      "id": "company_01h455vb4pex5vsknk084sn02q",
      "external_id": "acme",
      "name": "Acme",
      "joined_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "email_preferences": [
    {
      "category": "post_updates",
      "email": false,
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "hearts": [
    {
      "comment_id": "comment_01h455vb4pex5vsknk084sn02q",
      "created_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "identities": [
    {
      "email": "dana@example.com",
      "provider": "google",
      "created_at": "2026-09-28T14:03:12.482Z",
      "last_used_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "notifications": [
    {
      "changelog_entry_id": null,
      "comment_id": null,
      "kind": "post_status_changed",
      "post_id": null,
      "created_at": "2026-09-28T14:03:12.482Z",
      "read_at": null
    }
  ],
  "posts": [
    {
      "id": "post_01h455vb4pex5vsknk084sn02q",
      "board": "Feature requests",
      "body_md": "Finance exports every report by hand.",
      "moderation_state": "approved",
      "number": 42,
      "status": "planned",
      "title": "Export reports to CSV",
      "visibility": "public",
      "created_at": "2026-09-28T14:03:12.482Z",
      "deleted_at": null
    }
  ],
  "profile": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "locale": "en",
    "name": "Dana Kim",
    "read_translations": true,
    "traits": {
      "plan": "enterprise",
      "seats": 40
    },
    "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
  },
  "sessions": [
    {
      "audience": "widget",
      "ip": null,
      "user_agent": null,
      "created_at": "2026-09-28T14:03:12.482Z",
      "expires_at": "2026-09-28T14:03:12.482Z",
      "last_seen_at": "2026-09-28T14:03:12.482Z",
      "revoked_at": null
    }
  ],
  "subscriptions": [
    {
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "reason": "author",
      "created_at": "2026-09-28T14:03:12.482Z",
      "unsubscribed_at": null
    }
  ],
  "votes": [
    {
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "post_title": "Export reports to CSV",
      "source": "portal",
      "created_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "exported_at": "2026-09-28T14:03:12.482Z"
}

The end user object#

Fields

  • idstring

    Starts with user_

  • avatar_urlstringnullable

    At most 2,048 characters

  • companiesarray of objects

    The companies the end user belongs to, the most valuable first.

    At most 20 items

    Fields of each item (4)
    • idstring

      Starts with company_

    • external_idstring

      At most 255 characters

    • namestringnullable

      At most 200 characters

    • valueinteger

      At least 0

  • emailstring · emailnullable
  • external_idstringnullable

    The customer's id in your system.

    At most 255 characters

  • kindstring

    user for a customer, team for the team's own rows (a team member acting as themselves, an issue tracker's connection, or an imported team author), and guest for someone who wrote in the portal without signing in.

    One ofuserteamguest
  • namestringnullable

    At most 100 characters

  • traitsobject

    The traits, by key. A date trait is a string such as 2026-09-28 or an RFC 3339 time.

    Each value is a string, number or boolean

  • created_atstring · date-time
  • updated_atstring · date-time
  • banned_atstring · date-timenullable

    Set while the end user is banned.

  • email_verified_atstring · date-timenullable

    When the end user proved they own the email by signing in with it. Null for an email set through the API.

  • erased_atstring · date-timenullable

    Set once the end user's personal data has been erased.

Example

The end user object
{
  "id": "user_01h455vb4pex5vsknk084sn02q",
  "avatar_url": null,
  "companies": [
    {
      "id": "company_01h455vb4pex5vsknk084sn02q",
      "external_id": "acme",
      "name": "Acme",
      "value": 120000
    }
  ],
  "email": "dana@example.com",
  "external_id": "u-8412",
  "kind": "user",
  "name": "Dana Kim",
  "traits": {
    "plan": "enterprise",
    "seats": 40
  },
  "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
}

The end user export object#

Everything Swingback keeps about an end user, for a data subject access request.

Fields

  • commentsarray of objects
    Fields of each item (8)
    • idstring

      Starts with comment_

    • body_mdstring
    • moderation_statestring

      approved content shows in the portal. held content waits for your team's review, and rejected content shows only to its author and your team. What your team and API keys create is always approved.

      One ofapprovedheldrejected
    • parent_idstringnullable

      Starts with comment_

    • post_idstring

      Starts with post_

    • visibilitystring

      public, or internal for a note for your team, which the portal never shows.

      One ofpublicinternal
    • created_atstring · date-time
    • deleted_atstring · date-timenullable
  • companiesarray of objects
    Fields of each item (4)
    • idstring

      Starts with company_

    • external_idstring

      At most 255 characters

    • namestringnullable

      At most 200 characters

    • joined_atstring · date-time
  • email_preferencesarray of objects

    Their email choices, by category.

    Fields of each item (3)
    • categorystring
      One ofpost_updateschangelogdigestnew_postsmoderationnew_commentsmentions
    • emailboolean
    • updated_atstring · date-time
  • heartsarray of objects

    The comments they liked.

    Fields of each item (2)
    • comment_idstring

      Starts with comment_

    • created_atstring · date-time
  • identitiesarray of objects

    The Google or GitHub accounts they sign in with.

    Fields of each item (4)
    • emailstringnullable

      At most 254 characters

    • providerstring
      One ofgooglegithub
    • created_atstring · date-time
    • last_used_atstring · date-time
  • notificationsarray of objects
    Fields of each item (6)
    • changelog_entry_idstringnullable

      Starts with entry_

    • comment_idstringnullable

      Starts with comment_

    • kindstring

      End users are notified about the posts they follow or wrote (post_*) and about the changelog. Members are notified about new posts and comments (post_created, comment_created), what waits for review (post_held, comment_held) and other members' internal notes. Both are notified once when a comment mentions them (mentioned).

      One ofpost_status_changedpost_commentedpost_votedpost_mergedpost_approvedchangelog_publishedpost_createdpost_heldcomment_createdcomment_heldinternal_note_createdmentioned
    • post_idstringnullable

      Starts with post_

    • created_atstring · date-time
    • read_atstring · date-timenullable
  • postsarray of objects
    Fields of each item (10)
    • idstring

      Starts with post_

    • boardstring

      The board's name.

    • body_mdstring
    • moderation_statestring

      approved content shows in the portal. held content waits for your team's review, and rejected content shows only to its author and your team. What your team and API keys create is always approved.

      One ofapprovedheldrejected
    • numberinteger
    • statusstring
      One ofpendingreviewplannedin_progresscompletedclosed
    • titlestring
    • visibilitystring

      public, or private: only your team and the post's author see it.

      One ofpublicprivate
    • created_atstring · date-time
    • deleted_atstring · date-timenullable
  • profileobject
    Child fields (14)
    • idstring

      Starts with user_

    • avatar_urlstringnullable

      At most 2,048 characters

    • emailstringnullable

      At most 254 characters

    • external_idstringnullable

      At most 255 characters

    • kindstring

      user for a customer, team for the team's own rows (a team member acting as themselves, an issue tracker's connection, or an imported team author), and guest for someone who wrote in the portal without signing in.

      One ofuserteamguest
    • localestringnullable

      The language of their emails, one of en, fr, de, es, it, pt and nl: the portal's language at their last sign-in, or the one they chose there. Null if neither is known.

    • namestringnullable

      At most 100 characters

    • read_translationsboolean

      Whether this person wants to read posts and comments in their own language when a workspace translates them (ai_translation). True unless they turned it off, and only they can change it. It's a preference for the reader's client: a read that names a language gets translations whatever this says. A workspace that doesn't translate has no translations for anyone.

    • traitsobject

      The traits, by key. A date trait is a string such as 2026-09-28 or an RFC 3339 time.

      Each value is a string, number or boolean

    • created_atstring · date-time
    • updated_atstring · date-time
    • banned_atstring · date-timenullable
    • email_verified_atstring · date-timenullable
    • erased_atstring · date-timenullable
  • sessionsarray of objects

    Their portal and widget sessions.

    Fields of each item (7)
    • audiencestring

      Where the session works: portal or widget.

    • ipstringnullable

      At most 64 characters

    • user_agentstringnullable

      At most 512 characters

    • created_atstring · date-time
    • expires_atstring · date-time
    • last_seen_atstring · date-time
    • revoked_atstring · date-timenullable
  • subscriptionsarray of objects

    The posts they follow, or unfollowed.

    Fields of each item (4)
    • post_idstring

      Starts with post_

    • reasonstring
      One ofauthorvotercommentermanual
    • created_atstring · date-time
    • unsubscribed_atstring · date-timenullable
  • votesarray of objects
    Fields of each item (4)
    • post_idstring

      Starts with post_

    • post_titlestring
    • sourcestring

      Where the vote came from: dashboard, api, portal or import, as on the vote object.

    • created_atstring · date-time
  • exported_atstring · date-time

Example

The end user export object
{
  "comments": [
    {
      "id": "comment_01h455vb4pex5vsknk084sn02q",
      "body_md": "We need this for quarterly reports too.",
      "moderation_state": "approved",
      "parent_id": null,
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "visibility": "public",
      "created_at": "2026-09-28T14:03:12.482Z",
      "deleted_at": null
    }
  ],
  "companies": [
    {
      "id": "company_01h455vb4pex5vsknk084sn02q",
      "external_id": "acme",
      "name": "Acme",
      "joined_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "email_preferences": [
    {
      "category": "post_updates",
      "email": false,
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "hearts": [
    {
      "comment_id": "comment_01h455vb4pex5vsknk084sn02q",
      "created_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "identities": [
    {
      "email": "dana@example.com",
      "provider": "google",
      "created_at": "2026-09-28T14:03:12.482Z",
      "last_used_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "notifications": [
    {
      "changelog_entry_id": null,
      "comment_id": null,
      "kind": "post_status_changed",
      "post_id": null,
      "created_at": "2026-09-28T14:03:12.482Z",
      "read_at": null
    }
  ],
  "posts": [
    {
      "id": "post_01h455vb4pex5vsknk084sn02q",
      "board": "Feature requests",
      "body_md": "Finance exports every report by hand.",
      "moderation_state": "approved",
      "number": 42,
      "status": "planned",
      "title": "Export reports to CSV",
      "visibility": "public",
      "created_at": "2026-09-28T14:03:12.482Z",
      "deleted_at": null
    }
  ],
  "profile": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "locale": "en",
    "name": "Dana Kim",
    "read_translations": true,
    "traits": {
      "plan": "enterprise",
      "seats": 40
    },
    "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
  },
  "sessions": [
    {
      "audience": "widget",
      "ip": null,
      "user_agent": null,
      "created_at": "2026-09-28T14:03:12.482Z",
      "expires_at": "2026-09-28T14:03:12.482Z",
      "last_seen_at": "2026-09-28T14:03:12.482Z",
      "revoked_at": null
    }
  ],
  "subscriptions": [
    {
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "reason": "author",
      "created_at": "2026-09-28T14:03:12.482Z",
      "unsubscribed_at": null
    }
  ],
  "votes": [
    {
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "post_title": "Export reports to CSV",
      "source": "portal",
      "created_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "exported_at": "2026-09-28T14:03:12.482Z"
}

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