Policy handbooks

Create a policy handbook

Writes a new policy handbook. It is queued for indexing straight away, so it comes back with indexStatus of Pending and only starts steering chats once indexing finishes.

POST

https://api.portal.magicdoor.com/company-app/policy-handbooks

Authorization

Authorizationstringrequired

Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Body

application/json

levelenum<string>

Which rung to attach the handbook at. Defaults to Global when left out.

GlobalPortfolioPropertyUnitLease

levelIdstring

The portfolio, property, unit or lease to attach it to. Leave it out when level is Global.

titlestringrequired

Name of the handbook, up to 255 characters.

descriptionstring

What the handbook covers, up to 2000 characters.

scriptstringrequired

The policy text, in plain text. This is what the AI is given.

enabledboolean

Whether to apply the handbook to live chats.

default: true

Response

200 · The handbook that was created, with indexing not yet finished.

idstring

The handbook. A Snowflake id sent as a decimal string.

levelenum<string>

Which rung of the hierarchy the handbook applies at. PascalCase, not camelCase.

GlobalPortfolioPropertyUnitLease

levelIdstring

The portfolio, property, unit or lease the handbook is attached to. Absent when level is Global.

titlestring

Name of the handbook.

descriptionstring

What the handbook covers. Absent when none was set.

scriptstring

The policy text itself, in plain text. This is what the AI is given.

indexStatusenum<string>

How far the handbook has got through being indexed for AI search. PascalCase, not camelCase.

PendingProcessingIndexedFailed

indexErrorstring

Why indexing failed. Present when indexStatus is Failed.

indexedAtstring · date-time

When the handbook was last indexed, in the company's timezone. Absent when it never has been.

enabledboolean

Whether the handbook is applied to live chats.

createdstring · date-time

When the handbook was created, in the company's timezone.

updatedstring · date-time

When it was last changed, in the company's timezone.

401 · The access token is missing, expired, or not valid for this company.

`level` and `indexStatus` are PascalCase

Most enums in this API come back camelCased. These two do not: they are turned into strings by hand, so you get Property and Indexed, not property and indexed. The level query filter is read the same way and is case-sensitive.

Levels stack, they do not override

A handbook is attached at one rung of the hierarchy, and every handbook that applies to a conversation is used together. A lease chat therefore picks up the company's global handbook, the portfolio's, the property's, the unit's and the lease's own, all at once. A more specific handbook does not replace a broader one.

`level`	What `levelId` holds
`Global`	Nothing. Leave it out; the handbook applies company-wide.
`Portfolio`	The portfolio's id. Applies to every property in it.
`Property`	The property's id. Applies to every unit in it.
`Unit`	The unit's id. Applies to every lease on it.
`Lease`	The lease's id. Applies to that lease only.

Indexing is asynchronous

Creating the handbook does not index it. Poll the handbook until indexStatus becomes Indexed, or watch for Failed and read indexError.