Safe Mode
The project Safe Mode object
Attributes
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
ceilingobjectrequiredStructured ceiling values for this native project safe mode.
Show 6 child fields
entitledbooleanrequiredWhether entitled.
entitlementReasonstringrequirednullableSpecifies entitlement reason for this native project safe mode.
{
"projectId": "00000000-0000-4000-8000-000000000000",
"ceiling": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"entitled": true,
"entitlementReason": "string"
}The number Safe Mode object
Attributes
sessionstringrequiredIdentifier of the connected Polymorfa session.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
projectobjectrequiredStructured project values for this native session safe mode.
Show 6 child fields
overrideobjectrequiredStructured override values for this native session safe mode.
Show 4 child fields
effectiveobjectrequiredStructured effective values for this native session safe mode.
Show 6 child fields
appliedobjectrequirednullableStructured applied values for this native session safe mode.
Show 5 child fields
mismatchbooleanrequiredWhether mismatch.
entitledbooleanrequiredWhether entitled.
entitlementReasonstringrequirednullableSpecifies entitlement reason for this native session safe mode.
{
"session": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"project": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"override": {
"presence": "inherit",
"typing": "inherit",
"reads": "inherit",
"pacing": "inherit"
},
"effective": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"applied": {
"observedAt": "string",
"presence": "string",
"typing": "string",
"reads": "string",
"pacing": "string"
},
"mismatch": true,
"entitled": true,
"entitlementReason": "string"
}Get project safe mode
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Project Safe Mode ceiling, and whether the plan includes BanSafe Lite
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 4 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/messaging/projects/<projectId>/safe-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"ceiling": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"entitled": true,
"entitlementReason": "string"
}
}Get session safe mode
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Path parameters
sessionstringrequiredmin length1Identifier of the connected Polymorfa session.
Responses
200Project ceiling, number override, the effective policy, and whether the plan includes BanSafe Lite
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 9 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/messaging/<session>/safe-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"session": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"project": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"override": {
"presence": "inherit",
"typing": "inherit",
"reads": "inherit",
"pacing": "inherit"
},
"effective": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"applied": {
"observedAt": "string",
"presence": "string",
"typing": "string",
"reads": "string",
"pacing": "string"
},
"mismatch": true,
"entitled": true,
"entitlementReason": "string"
}
}Update project safe mode
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Sets the most visible behaviour any number in this project may use. Presence and read receipts are visible to the people this number messages: turning them on makes the number appear online, exposes last-seen subject to the account's privacy settings, and puts blue ticks on incoming messages. Every axis is off by default and only this request changes it.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Body
presencestringSpecifies presence for this schema.
Allowed valuesdarkonline_while_sendingonline_hourstypingstringSpecifies typing for this schema.
Allowed valuesoffbefore_textbefore_allreadsstringSpecifies reads for this schema.
Allowed valuesoffreplied_chatsall_inboundpacingstringSpecifies pacing for this schema.
Allowed valuesoffjitteredconversationonlineStartintegerrange0–23Specifies online start for this schema.
onlineEndintegerrange0–23Specifies online end for this schema.
Responses
200Project Safe Mode ceiling updated
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 4 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
402`safe_mode_not_entitled`: Safe Mode is part of BanSafe Lite, which is not included on this number's plan
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
503Stored, but a connected number did not confirm the policy; retry the request
curl -X PUT "https://api.polymorfa.com/messaging/projects/<projectId>/safe-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
}'{
"success": true,
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"ceiling": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"entitled": true,
"entitlementReason": "string"
}
}Update session safe mode
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Sets one number's Safe Mode. Each axis accepts inherit to follow the project ceiling. An override may only be equally or more conservative than the ceiling; a more visible value is refused with safe_mode_exceeds_project_ceiling.
Path parameters
sessionstringrequiredmin length1Identifier of the connected Polymorfa session.
Body
presencestringSpecifies presence for this schema.
Allowed valuesinheritdarkonline_while_sendingonline_hourstypingstringSpecifies typing for this schema.
Allowed valuesinheritoffbefore_textbefore_allreadsstringSpecifies reads for this schema.
Allowed valuesinheritoffreplied_chatsall_inboundpacingstringSpecifies pacing for this schema.
Allowed valuesinheritoffjitteredconversation
Responses
200Number Safe Mode override updated
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 9 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
402`safe_mode_not_entitled`: Safe Mode is part of BanSafe Lite, which is not included on this number's plan
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
503Stored, but a connected number did not confirm the policy; retry the request
curl -X PUT "https://api.polymorfa.com/messaging/<session>/safe-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"presence": "inherit",
"typing": "inherit",
"reads": "inherit",
"pacing": "inherit"
}'{
"success": true,
"data": {
"session": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"project": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"override": {
"presence": "inherit",
"typing": "inherit",
"reads": "inherit",
"pacing": "inherit"
},
"effective": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"applied": {
"observedAt": "string",
"presence": "string",
"typing": "string",
"reads": "string",
"pacing": "string"
},
"mismatch": true,
"entitled": true,
"entitlementReason": "string"
}
}