Skip to content
Swingback, home

API reference

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

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

List companies#

GET/v1/workspaces/{workspace_id}/companies

Any API key: Read or Read and write

Returns the workspace's companies, the most valuable first.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

Query parameters

  • external_idstring

    Only the company with this id in your system.

    1 to 255 characters

  • 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/companies" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"
Response · 200 OK
{
  "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#

POST/v1/workspaces/{workspace_id}/companies

An 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_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 company, found by its external_id. Fields you don't send stay as they are.

  • 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

Responses

Example

Request
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
  }'
Response · 200 OK
{
  "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#

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

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

    Starts with ws_

  • company_idstringrequired

    The company's id.

    Starts with company_

Responses

Example

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

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

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

    Starts with ws_

  • company_idstringrequired

    The company's id.

    Starts with company_

Responses

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

Example

Request
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

  • idstring

    Starts with company_

  • domainstringnullable

    At most 253 characters

  • external_idstring

    The company's id in your system.

    At most 255 characters

  • member_countinteger

    How many end users belong to the company.

  • namestringnullable

    At most 200 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

  • valueinteger

    What the company is worth to you, such as its monthly revenue in cents.

    At least 0

  • created_atstring · date-time
  • updated_atstring · date-time

Example

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

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