Traits
Traits are typed attributes of end users and companies: string, number, boolean or date. The first value sent for a new key defines its type, and later values must have that type. To give a trait the type date, define it before sending its values.
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 traits#
/ v1/ workspaces/ {workspace_id}/ traitsAny API key: Read or Read and write
Returns the trait definitions, sorted by subject, then key, in a single page: a workspace has at most 50 per subject.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
subjectstringOnly the traits of end users, or only those of companies. Both by default.
One ofend_usercompany
Responses
- 200OKThe trait definitions. The trait definition objects are all in
data. - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/traits?subject=end_user" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"data": [
{
"id": "trait_01h455vb4pex5vsknk084sn02q",
"key": "plan",
"subject": "end_user",
"type": "string",
"created_at": "2026-09-28T14:03:12.482Z"
}
],
"next_cursor": null,
"has_more": false
}Define a trait#
/ v1/ workspaces/ {workspace_id}/ traitsAn API key with Read and write access
Defines a key before any value is sent for it. This is how a trait gets the type date. A key that's already defined returns 409 trait_defined: to change its type, delete the trait first.
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/jsonrequiredkeystringrequiredThe trait's key, a letter followed by up to 63 letters, digits or underscores.
subjectstringrequiredWhat the trait describes:
end_userfor end users,companyfor companies.One ofend_usercompanytypestringrequiredThe type of the trait's values. A
datetakes2026-09-28or an RFC 3339 time.One ofstringnumberbooleandate
Responses
- 201CreatedThe new trait definition object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST "$SWINGBACK_API/traits" \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": "company",
"key": "renewal_date",
"type": "date"
}'{
"id": "trait_01h455vb4pex5vsknk084sn02q",
"key": "renewal_date",
"subject": "company",
"type": "date",
"created_at": "2026-09-28T14:03:12.482Z"
}Delete a trait#
/ v1/ workspaces/ {workspace_id}/ traits/ {trait_id}An API key with Read and write access
Deletes the trait's definition and every value of it.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_trait_idstringrequiredThe trait's id.
Starts with
trait_
Responses
- 204No ContentThe trait and its values were deleted.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X DELETE \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/traits/trait_01h455vb4pex5vsknk084sn02q" The response is 204 No Content, with no body.
The trait definition object#
Fields
idstringStarts with
trait_keystringThe trait's key, a letter followed by up to 63 letters, digits or underscores.
subjectstringWhat the trait describes:
end_userfor end users,companyfor companies.One ofend_usercompanytypestringThe type of the trait's values. A
datetakes2026-09-28or an RFC 3339 time.One ofstringnumberbooleandatecreated_atstring · date-time
Example
{
"id": "trait_01h455vb4pex5vsknk084sn02q",
"key": "plan",
"subject": "end_user",
"type": "string",
"created_at": "2026-09-28T14:03:12.482Z"
}