Skip to content
oHallo Developers

Policies

Policies define rules, constraints, and procedures that govern how the AI behaves. Unlike knowledge base entries (which answer factual questions), policies establish behavioural guidelines — escalation triggers, verification steps, response constraints, and business rules.

Required scope: policy:read for GET endpoints, policy:write for write endpoints.

List entries

Section titled “List entries”

Retrieve all policy entries for a workspace.

Terminal window
curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/policy-entries" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

ParameterTypeRequiredDescription
topicstringNoFilter by topic
statusstringNoFilter by status: approved, pending_review, rejected
limitintegerNoMax items to return (default 50, max 100)
offsetintegerNoNumber of items to skip (default 0)

Response:

{
  "items": [
    {
      "id": "11223344-5566-4788-99aa-bbccddeeff00",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "topic": "escalation",
      "ruleText": "If the customer mentions legal action, litigation, or a lawyer, immediately flag the conversation for human review and do not attempt to resolve the issue autonomously.",
      "conditions": {
        "keywords": ["legal action", "litigation", "lawyer", "court"]
      },
      "sourceType": "manual",
      "status": "approved",
      "confidence": null,
      "createdAt": "2026-01-10T09:00:00.000Z",
      "updatedAt": "2026-01-10T09:00:00.000Z"
    }
  ],
  "total": 12
}

Search entries

Section titled “Search entries”

Search policy entries by semantic similarity.

Terminal window
curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/policy-entries/search?q=when%20to%20escalate" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

ParameterTypeRequiredDescription
qstringYesSearch query

Response:

{
  "items": [
    {
      "id": "11223344-5566-4788-99aa-bbccddeeff00",
      "topic": "escalation",
      "ruleText": "If the customer mentions legal action, litigation, or a lawyer, immediately flag the conversation for human review and do not attempt to resolve the issue autonomously.",
      "conditions": {
        "keywords": ["legal action", "litigation", "lawyer", "court"]
      },
      "status": "approved"
    }
  ],
  "total": 2
}

List pending entries

Section titled “List pending entries”

Retrieve policy entries awaiting human review.

Terminal window
curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/policy-entries/pending" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "items": [
    {
      "id": "aabbccdd-eeff-4788-9233-445566778899",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "topic": "order-verification",
      "ruleText": "Before looking up order details, always ask the customer to confirm their order number. Do not search by name or email alone.",
      "conditions": null,
      "sourceType": "extracted",
      "sourceConversationId": "c9f8e7d6-b5a4-3210-fedc-ba9876543210",
      "status": "pending_review",
      "confidence": 0.72,
      "createdAt": "2026-03-14T16:30:00.000Z",
      "updatedAt": "2026-03-14T16:30:00.000Z"
    }
  ],
  "total": 3
}

Create entry

Section titled “Create entry”

Create a new policy entry. Entries created via the API are set to approved status by default.

Required scope: policy:write

Terminal window
curl -X POST "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/policy-entries" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "pricing",
    "ruleText": "Never disclose wholesale pricing or volume discount tiers to end customers. If asked about bulk pricing, direct them to their account manager.",
    "conditions": {
      "accountTypes": ["end_customer"]
    }
  }'

Request body:

FieldTypeRequiredDescription
topicstringYesTopic category for the policy
ruleTextstringYesThe rule or instruction text
conditionsobjectNoOptional structured conditions for contextual matching

Response:

{
  "id": "ffeeddcc-bbaa-4788-9776-554433221100",
  "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "topic": "pricing",
  "ruleText": "Never disclose wholesale pricing or volume discount tiers to end customers. If asked about bulk pricing, direct them to their account manager.",
  "conditions": {
    "accountTypes": ["end_customer"]
  },
  "sourceType": "manual",
  "status": "approved",
  "confidence": null,
  "createdAt": "2026-03-15T15:30:00.000Z",
  "updatedAt": "2026-03-15T15:30:00.000Z"
}

Update entry

Section titled “Update entry”

Update an existing policy entry. Only the fields you include are changed.

Required scope: policy:write

Terminal window
curl -X PATCH "https://api.ohallo.eu/api/policy-entries/ffeeddcc-bbaa-4788-7766-554433221100" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "ruleText": "Never disclose wholesale pricing, volume discount tiers, or partner-specific rates to end customers. If asked about bulk pricing, direct them to their account manager or provide the general inquiry form link."
  }'

Response: Returns the full updated entry.

Approve entry

Section titled “Approve entry”

Approve a pending policy entry, making it active for the AI.

Required scope: policy:write

Terminal window
curl -X POST "https://api.ohallo.eu/api/policy-entries/aabbccdd-eeff-4788-2233-445566778899/approve" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Reject entry

Section titled “Reject entry”

Reject a pending policy entry. Optionally include a reason.

Required scope: policy:write

Terminal window
curl -X POST "https://api.ohallo.eu/api/policy-entries/aabbccdd-eeff-4788-2233-445566778899/reject" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "This is too restrictive -- we do allow order lookups by email for verified accounts."
  }'

Delete entry

Section titled “Delete entry”

Permanently delete a policy entry.

Required scope: policy:write

Terminal window
curl -X DELETE "https://api.ohallo.eu/api/policy-entries/ffeeddcc-bbaa-4788-7766-554433221100" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response: 204 No Content on success.

Policy structure

Section titled “Policy structure”

Each policy entry has three key fields:

topic — A category string that groups related policies. The Policy Agent retrieves policies by topic based on the conversation’s classified intents. Examples: escalation, pricing, returns, verification, tone.

ruleText — The actual rule or instruction, written in natural language. Be specific and actionable. The AI interprets this text literally, so avoid ambiguity.

conditions — Optional structured data for contextual matching. Conditions are free-form JSON and can represent any filtering criteria relevant to your business logic. The Policy Agent uses conditions to determine whether a policy applies to the current conversation context.

Effective policy writing

Section titled “Effective policy writing”

Good policies are specific, actionable, and testable:

Topic: returns
Rule: Accept return requests for items delivered within the last 30 days.
      Require the order number and reason for return. If the item is
      damaged, request a photo before processing.

Avoid vague policies that the AI cannot act on consistently:

Topic: general
Rule: Be helpful and try to resolve issues.

Looking for the product? Visit ohallo.eu  ·  Help Centre  ·  Contact

Copyright 2026 oHallo ApS. All rights reserved.