Log InContact
Browse the docs

API reference

Entities

Units of the account, such as the clubs of a franchise or the clients of a call center, that group agents, phone numbers and webhooks.

GET/v1/entitiesPOST/v1/entitiesGET/v1/entities/{entityId}PATCH/v1/entities/{entityId}DELETE/v1/entities/{entityId}POST/v1/entities/{entityId}/move-items

List entities

GET/v1/entities
Bearer API key

An entity is a subdivision of your account — a club of a franchise, a client of a call center, a practice — that groups agents, phone numbers and webhooks. Items that belong to no entity are shared and usable by every entity. An entity is not a security boundary: every API key sees the whole account.

Entities are sorted by name, each with the number of agents, phone numbers and webhooks it holds.

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Query parameters

pageinteger
minimum 1default 1example 1
limitinteger
from 1 to 100default 50example 50
externalIdstring

Return only the entity with this exact external id.

1 to 255 charactersexample club-42

Responses

Entities listed successfully

dataobject[]required
Show child attributes
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
namestringrequired
1 to 255 charactersexample Lyon Part-Dieu
externalIdstring | nullrequired

Your own identifier for the entity, unique within the account.

1 to 255 charactersexample club-42
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstringrequired
example 2026-01-01T00:00:00.000Z
usageobjectrequired

What the entity holds. Deleted agents and numbers are not counted.

Show child attributes
agentsintegerrequired
example 3
phoneNumbersintegerrequired
example 2
webhooksintegerrequired
example 1
pageCountnumberrequired
example 3

Invalid request

successenum<boolean>required
Allowedfalse
errorobjectrequired
Show child attributes
nameenum<string>required
AllowedZodError
issuesobject[]required
Show child attributes
codestringrequired
example invalid_enum_value
pathstring | number[]required
messagestringrequired
example Invalid email

Unauthorized

errorstringrequired

Internal server error

errorstringrequired
GET
curl "https://api.callshift.ai/v1/entities?externalId=club-42" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY"
const res = await fetch("https://api.callshift.ai/v1/entities?externalId=club-42", {
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
  },
});
const data = await res.json();
import os
import requests

res = requests.get(
    "https://api.callshift.ai/v1/entities?externalId=club-42",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
)
print(res.json())
Response
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Lyon Part-Dieu",
      "externalId": "club-42",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "usage": {
        "agents": 3,
        "phoneNumbers": 2,
        "webhooks": 1
      }
    }
  ],
  "pageCount": 3
}
{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "invalid_enum_value",
        "path": [
          "contacts",
          0,
          "email"
        ],
        "message": "Invalid email"
      }
    ]
  }
}
{
  "error": "Authentication error"
}
{
  "error": "Internal server error"
}

Create an entity

POST/v1/entities
Bearer API key

An entity is a subdivision of your account — a club of a franchise, a client of a call center, a practice — that groups agents, phone numbers and webhooks. Items that belong to no entity are shared and usable by every entity. An entity is not a security boundary: every API key sees the whole account.

The name and the external id must each be unique within the account. When the external id is taken, the 409 carries the id of the entity that holds it, so provisioning can be retried safely.

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Body application/json

namestringrequired
1 to 255 charactersexample Lyon Part-Dieu
externalIdstring | null

Your own identifier for the entity, unique within the account.

1 to 255 charactersexample club-42

Responses

Entity created successfully

idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
namestringrequired
1 to 255 charactersexample Lyon Part-Dieu
externalIdstring | nullrequired

Your own identifier for the entity, unique within the account.

1 to 255 charactersexample club-42
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstringrequired
example 2026-01-01T00:00:00.000Z

Invalid request

successenum<boolean>required
Allowedfalse
errorobjectrequired
Show child attributes
nameenum<string>required
AllowedZodError
issuesobject[]required
Show child attributes
codestringrequired
example invalid_enum_value
pathstring | number[]required
messagestringrequired
example Invalid email

Unauthorized

errorstringrequired

The name or the external id is already used by another entity

errorstringrequired
existingEntityIdstring<uuid>

Set when the external id is taken: the entity that holds it, so a retried provisioning can adopt it.

example 550e8400-e29b-41d4-a716-446655440000

Internal server error

errorstringrequired
POST
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"
  }'
const res = await fetch("https://api.callshift.ai/v1/entities", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Lyon Part-Dieu",
    "externalId": "club-42"
  }),
});
const data = await res.json();
import os
import requests

res = requests.post(
    "https://api.callshift.ai/v1/entities",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
    json={
        "name": "Lyon Part-Dieu",
        "externalId": "club-42",
    },
)
print(res.json())
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Lyon Part-Dieu",
  "externalId": "club-42",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "invalid_enum_value",
        "path": [
          "contacts",
          0,
          "email"
        ],
        "message": "Invalid email"
      }
    ]
  }
}
{
  "error": "Authentication error"
}
{
  "error": "The name or the external id is already used by another entity",
  "existingEntityId": "550e8400-e29b-41d4-a716-446655440000"
}
{
  "error": "Internal server error"
}

Get an entity

GET/v1/entities/{entityId}
Bearer API key

Get a single entity by id. To look one up by your own identifier, list entities with the externalId filter.

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Path parameters

entityIdstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000

Responses

Entity retrieved successfully

idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
namestringrequired
1 to 255 charactersexample Lyon Part-Dieu
externalIdstring | nullrequired

Your own identifier for the entity, unique within the account.

1 to 255 charactersexample club-42
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstringrequired
example 2026-01-01T00:00:00.000Z

Unauthorized

errorstringrequired

Entity not found

errorstringrequired

Internal server error

errorstringrequired
GET
curl "https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY"
const res = await fetch("https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000", {
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
  },
});
const data = await res.json();
import os
import requests

res = requests.get(
    "https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
)
print(res.json())
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Lyon Part-Dieu",
  "externalId": "club-42",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
{
  "error": "Authentication error"
}
{
  "error": "Entity not found"
}
{
  "error": "Internal server error"
}

Update an entity

PATCH/v1/entities/{entityId}
Bearer API key

Rename an entity, or change or remove its external id.

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Path parameters

entityIdstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000

Body application/json

namestring
1 to 255 charactersexample Lyon Part-Dieu
externalIdstring | null

null removes the external id.

1 to 255 charactersexample club-42

Responses

Entity updated successfully

idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
namestringrequired
1 to 255 charactersexample Lyon Part-Dieu
externalIdstring | nullrequired

Your own identifier for the entity, unique within the account.

1 to 255 charactersexample club-42
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstringrequired
example 2026-01-01T00:00:00.000Z

Invalid request

successenum<boolean>required
Allowedfalse
errorobjectrequired
Show child attributes
nameenum<string>required
AllowedZodError
issuesobject[]required
Show child attributes
codestringrequired
example invalid_enum_value
pathstring | number[]required
messagestringrequired
example Invalid email

Unauthorized

errorstringrequired

Entity not found

errorstringrequired

The name or the external id is already used by another entity

errorstringrequired
existingEntityIdstring<uuid>

Set when the external id is taken: the entity that holds it, so a retried provisioning can adopt it.

example 550e8400-e29b-41d4-a716-446655440000

Internal server error

errorstringrequired
PATCH
curl -X PATCH "https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lyon Part-Dieu Centre"
  }'
const res = await fetch("https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Lyon Part-Dieu Centre"
  }),
});
const data = await res.json();
import os
import requests

res = requests.patch(
    "https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
    json={
        "name": "Lyon Part-Dieu Centre",
    },
)
print(res.json())
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Lyon Part-Dieu",
  "externalId": "club-42",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "invalid_enum_value",
        "path": [
          "contacts",
          0,
          "email"
        ],
        "message": "Invalid email"
      }
    ]
  }
}
{
  "error": "Authentication error"
}
{
  "error": "Entity not found"
}
{
  "error": "The name or the external id is already used by another entity",
  "existingEntityId": "550e8400-e29b-41d4-a716-446655440000"
}
{
  "error": "Internal server error"
}

Delete an entity

DELETE/v1/entities/{entityId}
Bearer API key

Delete an entity that holds nothing. While it still holds agents, phone numbers or webhooks the request is refused with what remains, rather than silently making those items shared.

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Path parameters

entityIdstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000

Responses

Entity deleted successfully

No content.

Unauthorized

errorstringrequired

Entity not found

errorstringrequired

The entity still holds agents, phone numbers or webhooks. Move them first.

errorstringrequired
usageobjectrequired

What the entity holds. Deleted agents and numbers are not counted.

Show child attributes
agentsintegerrequired
example 3
phoneNumbersintegerrequired
example 2
webhooksintegerrequired
example 1

Internal server error

errorstringrequired
DELETE
curl -X DELETE "https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY"
const res = await fetch("https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
  },
});
console.log(res.status); // 204
import os
import requests

res = requests.delete(
    "https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
)
print(res.status_code)  # 204
Response
No content
{
  "error": "Authentication error"
}
{
  "error": "Entity not found"
}
{
  "error": "The entity still holds agents, phone numbers or webhooks. Move them first",
  "usage": {
    "agents": 3,
    "phoneNumbers": 2,
    "webhooks": 1
  }
}
{
  "error": "Internal server error"
}

Move everything an entity holds

POST/v1/entities/{entityId}/move-items
Bearer API key

Move all of the entity's agents, phone numbers and webhooks to another entity, or make them shared, so it can be merged into another or wound down and then deleted. The entity itself is kept, and the calls it made keep it.

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Path parameters

entityIdstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000

Body application/json

entityIdstring<uuid> | null

The entity to move the items to, or null to make them shared. Send this or entityExternalId.

example 550e8400-e29b-41d4-a716-446655440000
entityExternalIdstring | null

Your external id of the entity to move the items to, or null to make them shared. Send this or entityId.

1 to 255 charactersexample club-42

Responses

How many of each item moved

movedobjectrequired

What the entity holds. Deleted agents and numbers are not counted.

Show child attributes
agentsintegerrequired
example 3
phoneNumbersintegerrequired
example 2
webhooksintegerrequired
example 1

Invalid request

successenum<boolean>required
Allowedfalse
errorobjectrequired
Show child attributes
nameenum<string>required
AllowedZodError
issuesobject[]required
Show child attributes
codestringrequired
example invalid_enum_value
pathstring | number[]required
messagestringrequired
example Invalid email

Unauthorized

errorstringrequired

The entity or the target entity was not found

errorstringrequired

Internal server error

errorstringrequired
POST
curl -X POST "https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000/move-items" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityExternalId": "club-7"
  }'
const res = await fetch("https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000/move-items", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "entityExternalId": "club-7"
  }),
});
const data = await res.json();
import os
import requests

res = requests.post(
    "https://api.callshift.ai/v1/entities/550e8400-e29b-41d4-a716-446655440000/move-items",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
    json={
        "entityExternalId": "club-7",
    },
)
print(res.json())
Response
{
  "moved": {
    "agents": 3,
    "phoneNumbers": 2,
    "webhooks": 1
  }
}
{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "invalid_enum_value",
        "path": [
          "contacts",
          0,
          "email"
        ],
        "message": "Invalid email"
      }
    ]
  }
}
{
  "error": "Authentication error"
}
{
  "error": "The entity or the target entity was not found"
}
{
  "error": "Internal server error"
}