Customers and companies

Where customers come from#

A customer shows up under Customers the first time they do something, or when you add them:

• They sign in to your portal, with a code sent to their email, with Google or GitHub when offered, or through your own sign-in page (Settings → Sign-in). A customer who already has that email, such as one you synced, is the one who signs in.
• Your widget signs them in with an identity token your server signs. It names them by their id in your product, their external_id, and can carry their email, name, traits and companies. See Signing in your users.
• Your servers sync them through the REST API, or name them as the author of a post, a vote or a comment.
• You add them with Add customer under Customers: an email, an external id or both, and a name.

People who write on the portal without signing in, where your portal takes guests, show as Guest. If they sign in later, what they wrote becomes theirs. Team members who post or vote as themselves show with a Team badge.

Sync customers from your servers#

POST /v1/workspaces/{workspace_id}/end-users creates a customer, or updates one. It finds them by external_id, else by email, so send at least one of them. Only the fields you send change.

curl https://api.swingback.dev/v1/workspaces/$SWINGBACK_WORKSPACE_ID/end-users \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_8412",
    "email": "dana@example.com",
    "name": "Dana Kim",
    "traits": { "plan": "business", "seats": 12 },
    "companies": [
      { "external_id": "acct_1043", "name": "Acme Inc.", "domain": "acme.com", "value": 490000 }
    ]
  }'

The answer is the customer: 201 when it's new, 200 when it existed.

• companies is the customer's whole list, up to 20: they leave any company you leave out. Leave the field out to keep their companies as they are.
• Each company is found by its external_id and created if it's new. The fields you send update it.
• value is a whole number in the unit you choose, such as monthly revenue in cents. Use the same unit for every company: posts add them up.
• In traits, only the keys you send change, and null removes one.
• An email that belongs to another customer is refused with 409 end_user_conflict.

Companies#

A company groups customers, such as the accounts of your product. It has an external id (its id in your system), a name, a domain and a value: what it's worth to you.

Companies come from the API (with each customer, or on their own with POST .../companies), from identity tokens, or from Add company under Companies, which lists the most valuable first. In the dashboard, you set a company's name, domain and value; which customers belong to it, and its traits, come from the API or identity tokens.

Deleting a company takes its members out of it and its value off the posts they vote for. The customers stay. If your tokens or the API name the company again, it comes back.

Traits#

Traits are what you know about a customer or a company: their plan, their seats, their renewal date. Each key has a type: text, number, yes or no, or date.

A key is defined the first time a value arrives for it, with that value's type, and later values must have the same type. The API refuses a value of another type (400), and an identity token's is dropped. Since a date looks like text, define date keys ahead under Settings → Traits: a key, whether it's for customers or companies, and a type.

• A key is a letter, then up to 63 letters, digits or underscores.
• Text is up to 256 characters. A date is 2026-09-28, or an RFC 3339 time.
• A workspace has up to 50 trait keys for customers, and 50 for companies.
• Deleting a key under Settings → Traits deletes its values everywhere. To change a key's type, delete it and define it again.

Rank posts by customer value#

A post's customer value is the sum of the values of the companies whose members vote for it. A company counts once per post, however many of its people voted, and a voter in two companies brings both. When you merge posts, the votes move, and their companies with them.

Under Posts, choose Customer value in the order menu: the requests your most valuable customers want come first. A post shows its customer value on its page, and in the list when it's above 0. The portal never shows it.

curl "https://api.swingback.dev/v1/workspaces/$SWINGBACK_WORKSPACE_ID/posts?sort=customer_value&limit=10" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"

The value is computed when you ask for it, so it follows every vote, membership and value change at once.

Filter by company#

On a company's page, Posts its members vote for opens Posts filtered to that company. In the API, company_id filters the post list (GET .../posts?company_id=company_01h455vb4pex5vsknk084sn02q), and the customer list to a company's members.

Erase a customer#

When someone asks you to delete their data, open them under Customers and choose Erase, or call DELETE /v1/workspaces/{workspace_id}/end-users/{end_user_id}.

• What goes: their email, name, avatar, external id and traits; their sessions, so they're signed out; their sign-in methods, the posts they follow, their companies, their notifications and their email choices.
• What stays: their posts, comments, votes and hearts, anonymous. Vote counts don't change.

Erasing can't be undone. If the same person signs in or is synced again later, they're a new customer. A team member can't be erased: remove them from the team instead.

Ban a customer#

Ban from the portal, on a customer's page, stops them from writing. They can still read the portal, but can't post, comment, vote, follow, heart, upload images or change their name. What they wrote stays. Lift the ban undoes it. See Moderation.