Docs menu

Agents and sessions

An agent is one of your people, known to Hospify only by the ID you give and a display name. Hospify never asks for their phone number, email, ID documents or photo.

Field	Required	Notes
`external_id`	Yes, in the URL	Your ID for the person, up to 128 characters. Every event Hospify sends you carries it.
`display_name`	When creating	What supervisors see on the Live SOS Board. An alias is fine.
`team`, `site`	No	Names, made the first time you use them. An SOS goes first to the supervisors of the same team or site.
`active`	No	Set to false when someone leaves: they can't get a session, and they stop counting for billing.

Create and update

PUT /v1/org/agents/{external_id} creates the agent the first time (201) and updates only the fields you send after that (200).

Node.js

await hospify.agents.upsert("AGT-20931", { display_name: "Field agent, Ikeja", team: "Ikeja", site: "Allen Avenue" });
await hospify.agents.upsert("AGT-20931", { active: false });   // they left

Many at once

POST /v1/org/agents/batch takes up to 500. Agents that fail come back in errors; the rest are saved.

Node.js

const result = await hospify.agents.batch(staff.map((s) => ({ external_id: s.id, display_name: s.alias, team: s.region })));
// { created: 412, updated: 88, errors: [] }

List and remove

GET /v1/org/agents pages through them (?limit=, ?after=, ?active=). DELETE /v1/org/agents/{external_id} removes the agent and erases every incident and location Hospify holds about them.

Node.js

for await (const agent of hospify.allAgents({ active: true })) {
  console.log(agent.external_id, agent.last_active_at);
}
await hospify.agents.remove("AGT-20931");

Sessions

POST /v1/org/agents/{external_id}/sessions returns a token for that one agent, valid for an hour. Mint it when the agent signs in to your app, behind your own sign in. The SDKs call your getToken again whenever Hospify says the token has expired, so an SOS never fails because a token ran out.

Response

{ "token": "hst_eyJvIjo0...", "expires_in": 3600, "agent": { "external_id": "AGT-20931", "display_name": "Field agent, Ikeja", ... } }