Monitor and integrate

Entities

An entity is a unit of your account: a club of a franchise, a client of a call center, a practice of a group. It groups agents, phone numbers and webhooks. Items in no entity are shared, and every entity can use them.

Organisation, not access control

Entities keep each unit's items apart and let you filter by unit. Every API key and every member still sees the whole account, and the account has one bill.

Provision an entity from your system

Give each entity your own identifier as externalId. If the identifier is already taken, the 409 returns the entity that holds it, so a provisioning script can be run again safely.

Terminal

curl -X POST "https://api.callshift.ai/v1/entities" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Lyon Part-Dieu", "externalId": "club-42" }'

# Run again: 409 { "error": "...", "existingEntityId": "550e8400-e29b-41d4-a716-446655440000" }

Put items in an entity

Every request that writes an agent, a number or a webhook takes entityId or entityExternalId (one of them, not both). null makes the item shared, and leaving the field out keeps its current entity.

JSON

{ "entityExternalId": "club-42" }

The same two parameters filter the lists of agents, phone numbers, SIP numbers, webhooks and trunks: GET /v1/agents?entityExternalId=club-42.

Items of two entities never mix

CallShift refuses with a 409, naming the items, any link between two different entities: a number and the agent answering it, a campaign's agent and its number, an agent and its webhook. A shared item links with anything. A campaign call whose agent and number ended up in different entities is not dialed (agent-line-entity-mismatch) and the campaign stops.

Merge or close an entity

POST/v1/entities/{entityId}/move-items moves all of an entity's agents, numbers and webhooks to another entity, or makes them shared. The entity, now empty, can be deleted with DELETE/v1/entities/{entityId}; while it still holds items, deletion is refused with what remains.

Calls by entity

The after-call webhook carries the call's entity. The calls API has no entity filter yet: for a per-entity view, list the entity's agents and filter calls by agentId.