Skip to content
Shortcut: /, ⌘K or Ctrl+K

Safe Mode

View as Markdown

The project Safe Mode object

Attributes

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • ceilingobjectrequired

    Structured ceiling values for this native project safe mode.

    Show 6 child fields
  • entitledbooleanrequired

    Whether entitled.

  • entitlementReasonstringrequirednullable

    Specifies entitlement reason for this native project safe mode.

The project Safe Mode object
{
  "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

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • projectobjectrequired

    Structured project values for this native session safe mode.

    Show 6 child fields
  • overrideobjectrequired

    Structured override values for this native session safe mode.

    Show 4 child fields
  • effectiveobjectrequired

    Structured effective values for this native session safe mode.

    Show 6 child fields
  • appliedobjectrequirednullable

    Structured applied values for this native session safe mode.

    Show 5 child fields
  • mismatchbooleanrequired

    Whether mismatch.

  • entitledbooleanrequired

    Whether entitled.

  • entitlementReasonstringrequirednullable

    Specifies entitlement reason for this native session safe mode.

The number Safe Mode object
{
  "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

GET/messaging/projects/{projectId}/safe-modeMessaging API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Path parameters

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Project Safe Mode ceiling, and whether the plan includes BanSafe Lite
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
GET /messaging/projects/{projectId}/safe-modecURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/projects/<projectId>/safe-mode" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/messaging/{session}/safe-modeMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

Responses

  • 200Project ceiling, number override, the effective policy, and whether the plan includes BanSafe Lite
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
GET /messaging/{session}/safe-modecURL
curl "https://api.polymorfa.com/messaging/<session>/safe-mode" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

PUT/messaging/projects/{projectId}/safe-modeMessaging API
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)required

    Identifier of the Polymorfa project that owns this resource.

Body

  • presencestring

    Specifies presence for this schema.

    Allowed valuesdarkonline_while_sendingonline_hours
  • typingstring

    Specifies typing for this schema.

    Allowed valuesoffbefore_textbefore_all
  • readsstring

    Specifies reads for this schema.

    Allowed valuesoffreplied_chatsall_inbound
  • pacingstring

    Specifies pacing for this schema.

    Allowed valuesoffjitteredconversation
  • onlineStartintegerrange0–23

    Specifies online start for this schema.

  • onlineEndintegerrange0–23

    Specifies online end for this schema.

Responses

  • 200Project Safe Mode ceiling updated
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
PUT /messaging/projects/{projectId}/safe-modecURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "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

PUT/messaging/{session}/safe-modeMessaging APILinked Device API
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 length1

    Identifier of the connected Polymorfa session.

Body

  • presencestring

    Specifies presence for this schema.

    Allowed valuesinheritdarkonline_while_sendingonline_hours
  • typingstring

    Specifies typing for this schema.

    Allowed valuesinheritoffbefore_textbefore_all
  • readsstring

    Specifies reads for this schema.

    Allowed valuesinheritoffreplied_chatsall_inbound
  • pacingstring

    Specifies pacing for this schema.

    Allowed valuesinheritoffjitteredconversation

Responses

  • 200Number Safe Mode override updated
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
PUT /messaging/{session}/safe-modecURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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"
  }
}