Companies
Companies are your customers' organizations, found by their id in your system (external_id). A company's value is what it's worth to you, such as its monthly revenue in cents. A post's customer_value adds up the values of the distinct companies whose members vote for it.
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 companies#
/ v1/ workspaces/ {workspace_id}/ companiesAny API key: Read or Read and write
Returns the workspace's companies, the most valuable first.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
external_idstringOnly the company with this id in your system.
1 to 255 characters
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 companies. The company objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/companies" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"data": [
{
"id": "company_01h455vb4pex5vsknk084sn02q",
"domain": "acme.example.com",
"external_id": "acme",
"member_count": 12,
"name": "Acme",
"traits": {
"plan": "enterprise",
"seats": 40
},
"value": 120000,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"next_cursor": null,
"has_more": false
}Create or update a company#
/ v1/ workspaces/ {workspace_id}/ companiesAn API key with Read and write access
Finds the company by external_id and updates the fields you send. If there's no match, creates the company. 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 company, found by its external_id. Fields you don't send stay as they are.
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
Responses
- 200OKThe existing company, updated. Returns a company object.
- 201CreatedThe new company object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST "$SWINGBACK_API/companies" \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_id": "acme",
"name": "Acme",
"domain": "acme.example.com",
"value": 120000
}'{
"id": "company_01h455vb4pex5vsknk084sn02q",
"domain": "acme.example.com",
"external_id": "acme",
"member_count": 12,
"name": "Acme",
"traits": {
"plan": "enterprise",
"seats": 40
},
"value": 120000,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}Retrieve a company#
/ v1/ workspaces/ {workspace_id}/ companies/ {company_id}Any API key: Read or Read and write
Returns a company, with its value, its traits and how many end users belong to it.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_company_idstringrequiredThe company's id.
Starts with
company_
Responses
- 200OKThe company object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/companies/company_01h455vb4pex5vsknk084sn02q" {
"id": "company_01h455vb4pex5vsknk084sn02q",
"domain": "acme.example.com",
"external_id": "acme",
"member_count": 12,
"name": "Acme",
"traits": {
"plan": "enterprise",
"seats": 40
},
"value": 120000,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}Delete a company#
/ v1/ workspaces/ {workspace_id}/ companies/ {company_id}An API key with Read and write access
Its members leave it, and its value no longer counts toward the customer_value of the posts they vote for.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_company_idstringrequiredThe company's id.
Starts with
company_
Responses
- 204No ContentThe company was deleted.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X DELETE \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/companies/company_01h455vb4pex5vsknk084sn02q" The response is 204 No Content, with no body.
The company object#
Fields
idstringStarts with
company_domainstringnullableAt most 253 characters
external_idstringThe company's id in your system.
At most 255 characters
member_countintegerHow many end users belong to the company.
namestringnullableAt most 200 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
valueintegerWhat the company is worth to you, such as its monthly revenue in cents.
At least 0
created_atstring · date-timeupdated_atstring · date-time
Example
{
"id": "company_01h455vb4pex5vsknk084sn02q",
"domain": "acme.example.com",
"external_id": "acme",
"member_count": 12,
"name": "Acme",
"traits": {
"plan": "enterprise",
"seats": 40
},
"value": 120000,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}