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):
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..." List end users#
/ v1/ workspaces/ {workspace_id}/ end-usersAny API key: Read or Read and write
Returns the workspace's end users, newest first.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
qstringMatches part of the name, the email or the external id, ignoring case.
1 to 100 characters
company_idstringOnly the members of this company.
Starts with
company_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 end users. The end user objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/end-users?q=dana" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"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#
/ v1/ workspaces/ {workspace_id}/ end-usersAn 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
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/jsonrequiredA customer, found by external_id, else by email. One of the two is required.
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
companiesarray of objectsAll 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_idstringrequiredThe company's id in your system, which finds it.
1 to 255 characters
namestringThe company's name.
1 to 200 characters
domainstringThe company's domain, such as
acme.com, stored in lowercase.1 to 253 characters
traitsobjectTraits 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
datetrait (see Define a trait) takes2026-09-28or 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
valueintegerWhat the company is worth to you, such as its monthly revenue in cents. A post's
customer_valueadds up the values of its voters' companies.At least 0
traitsobjectTraits 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
datetrait (see Define a trait) takes2026-09-28or 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
- 200OKThe existing customer, updated. Returns an end user object.
- 201CreatedThe new customer. Returns an end user object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
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
}
]
}'{
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_end_user_idstringrequiredThe end user's id.
Starts with
user_
Responses
- 200OKThe end user object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/end-users/user_01h455vb4pex5vsknk084sn02q" {
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_end_user_idstringrequiredThe end user's id.
Starts with
user_
Responses
- 200OKThe erased end user object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X DELETE \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/end-users/user_01h455vb4pex5vsknk084sn02q" {
"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#
/ v1/ workspaces/ {workspace_id}/ end-users/ {end_user_id}/ exportAny 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_end_user_idstringrequiredThe end user's id.
Starts with
user_
Responses
- 200OKThe end user's data. Returns an end user export object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/end-users/user_01h455vb4pex5vsknk084sn02q/export" {
"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
idstringStarts with
user_avatar_urlstringnullableAt most 2,048 characters
companiesarray of objectsThe companies the end user belongs to, the most valuable first.
At most 20 items
Fields of each item (4)
idstringStarts with
company_external_idstringAt most 255 characters
namestringnullableAt most 200 characters
valueintegerAt least 0
emailstring · emailnullableexternal_idstringnullableThe customer's id in your system.
At most 255 characters
kindstringuserfor a customer,teamfor the team's own rows (a team member acting as themselves, an issue tracker's connection, or an imported team author), andguestfor someone who wrote in the portal without signing in.One ofuserteamguestnamestringnullableAt most 100 characters
traitsobjectThe traits, by key. A
datetrait is a string such as2026-09-28or an RFC 3339 time.Each value is a string, number or boolean
created_atstring · date-timeupdated_atstring · date-timebanned_atstring · date-timenullableSet while the end user is banned.
email_verified_atstring · date-timenullableWhen the end user proved they own the email by signing in with it. Null for an email set through the API.
erased_atstring · date-timenullableSet once the end user's personal data has been erased.
Example
{
"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 objectsFields of each item (8)
idstringStarts with
comment_body_mdstringmoderation_statestringapprovedcontent shows in the portal.heldcontent waits for your team's review, andrejectedcontent shows only to its author and your team. What your team and API keys create is always approved.One ofapprovedheldrejectedparent_idstringnullableStarts with
comment_post_idstringStarts with
post_visibilitystringpublic, orinternalfor a note for your team, which the portal never shows.One ofpublicinternalcreated_atstring · date-timedeleted_atstring · date-timenullable
companiesarray of objectsFields of each item (4)
idstringStarts with
company_external_idstringAt most 255 characters
namestringnullableAt most 200 characters
joined_atstring · date-time
email_preferencesarray of objectsTheir email choices, by category.
Fields of each item (3)
categorystringOne ofpost_updateschangelogdigestnew_postsmoderationnew_commentsmentionsemailbooleanupdated_atstring · date-time
heartsarray of objectsThe comments they liked.
Fields of each item (2)
comment_idstringStarts with
comment_created_atstring · date-time
identitiesarray of objectsThe Google or GitHub accounts they sign in with.
Fields of each item (4)
emailstringnullableAt most 254 characters
providerstringOne ofgooglegithubcreated_atstring · date-timelast_used_atstring · date-time
notificationsarray of objectsFields of each item (6)
changelog_entry_idstringnullableStarts with
entry_comment_idstringnullableStarts with
comment_kindstringEnd 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_createdmentionedpost_idstringnullableStarts with
post_created_atstring · date-timeread_atstring · date-timenullable
postsarray of objectsFields of each item (10)
idstringStarts with
post_boardstringThe board's name.
body_mdstringmoderation_statestringapprovedcontent shows in the portal.heldcontent waits for your team's review, andrejectedcontent shows only to its author and your team. What your team and API keys create is always approved.One ofapprovedheldrejectednumberintegerstatusstringOne ofpendingreviewplannedin_progresscompletedclosedtitlestringvisibilitystringpublic, orprivate: only your team and the post's author see it.One ofpublicprivatecreated_atstring · date-timedeleted_atstring · date-timenullable
profileobjectChild fields (14)
idstringStarts with
user_avatar_urlstringnullableAt most 2,048 characters
emailstringnullableAt most 254 characters
external_idstringnullableAt most 255 characters
kindstringuserfor a customer,teamfor the team's own rows (a team member acting as themselves, an issue tracker's connection, or an imported team author), andguestfor someone who wrote in the portal without signing in.One ofuserteamguestlocalestringnullableThe language of their emails, one of
en,fr,de,es,it,ptandnl: the portal's language at their last sign-in, or the one they chose there. Null if neither is known.namestringnullableAt most 100 characters
read_translationsbooleanWhether 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 alanguagegets translations whatever this says. A workspace that doesn't translate has no translations for anyone.traitsobjectThe traits, by key. A
datetrait is a string such as2026-09-28or an RFC 3339 time.Each value is a string, number or boolean
created_atstring · date-timeupdated_atstring · date-timebanned_atstring · date-timenullableemail_verified_atstring · date-timenullableerased_atstring · date-timenullable
sessionsarray of objectsTheir portal and widget sessions.
Fields of each item (7)
audiencestringWhere the session works:
portalorwidget.ipstringnullableAt most 64 characters
user_agentstringnullableAt most 512 characters
created_atstring · date-timeexpires_atstring · date-timelast_seen_atstring · date-timerevoked_atstring · date-timenullable
subscriptionsarray of objectsThe posts they follow, or unfollowed.
Fields of each item (4)
post_idstringStarts with
post_reasonstringOne ofauthorvotercommentermanualcreated_atstring · date-timeunsubscribed_atstring · date-timenullable
votesarray of objectsFields of each item (4)
post_idstringStarts with
post_post_titlestringsourcestringWhere the vote came from:
dashboard,api,portalorimport, as on the vote object.created_atstring · date-time
exported_atstring · date-time
Example
{
"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"
}