Worked request and response samples

Copy a request as written, substitute your own team and member ids, and compare the response envelope. Successful writes return { data, meta }; failures return the { error, meta } envelope. The retry-vs-surface matrix for every class sits at the bottom of this page. Teams back the routing-rule assign_team action: inbox and voice routing rules resolve a group to a load-balanced member from this roster. Reads below list the roster and its members; writes create and tune the group new rules point at.

Create a team

POST /api/v1/teams

Creates the group and returns the full team row in the 201 envelope. name must be unique within your workspace; active: false keeps the group out of routing assignment while you populate its members. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/teams" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tier 1 Support",
    "description": "Front-line agents handling inbound chat and voice",
    "active": true
  }'

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/teams", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Tier 1 Support",
    description: "Front-line agents handling inbound chat and voice",
    active: true,
  }),
});
console.log(await res.json());

Response

{
  "data": {
    "id": "team_4f9a1c2b8d3e5f60718293a4b5c6d7",
    "name": "Tier 1 Support",
    "description": "Front-line agents handling inbound chat and voice",
    "active": true,
    "created_at": "2026-09-10T09:41:12.884Z",
    "updated_at": "2026-09-10T09:41:12.884Z"
  },
  "meta": {
    "request_id": "req_teams_created_01",
    "timestamp": "2026-09-10T09:41:12.901Z"
  }
}

Recreating the same name returns a 409 CONFLICT telling you the name is taken — pick a new name or PATCH the existing team instead of blind-retrying:

409

{
  "error": {
    "code": "CONFLICT",
    "message": "Team name \"Tier 1 Support\" already exists",
    "status": 409
  },
  "meta": {
    "request_id": "req_teams_conflict_01",
    "timestamp": "2026-09-10T09:41:15.112Z"
  }
}

List members of a team

GET /api/v1/teams/{id}/members

Pages the roster oldest-first with keyset pagination. limit defaults to 25 and caps at 100; when meta.pagination.has_more is true, pass meta.pagination.cursor back as the cursor query parameter for the next page. total counts the whole team regardless of the cursor. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/teams/team_4f9a1c2b8d3e5f60718293a4b5c6d7/members?limit=25" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const teamId = "team_4f9a1c2b8d3e5f60718293a4b5c6d7";
const res = await fetch(
  `https://api.orbit.devotel.io/api/v1/teams/${teamId}/members?limit=25`,
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

Response

{
  "data": [
    {
      "id": "tmem_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3",
      "team_id": "team_4f9a1c2b8d3e5f60718293a4b5c6d7",
      "user_id": "usr_3f8a1c2b9d4e5f60718293a4b5c6d7e8",
      "active": true,
      "last_assigned_at": "2026-09-09T17:02:44.310Z",
      "created_at": "2026-09-01T08:12:03.115Z"
    }
  ],
  "meta": {
    "request_id": "req_teams_members_01",
    "timestamp": "2026-09-10T09:43:02.411Z",
    "pagination": {
      "cursor": "2026-09-01T08:12:03.115Z|tmem_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3",
      "has_more": true,
      "total": 47
    }
  }
}

Members are ordered oldest-first by (created_at, id), and active: false members stay listed but are skipped by load-balanced assignment. When total saturates the display cap (1,000), meta.pagination.total_capped: true is set so a UI can render “1,000+” — paging still walks every member via the cursor.

Update routing assignment availability

PATCH /api/v1/teams/{id}

Repauses the group. Setting active: false pulls the team out of routing-rule assign_team resolution without deleting it or its roster; flip it back to true to resume. Any subset of name, description, and active is accepted — unset fields are untouched. Request

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/teams/team_4f9a1c2b8d3e5f60718293a4b5c6d7" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Node.js

const teamId = "team_4f9a1c2b8d3e5f60718293a4b5c6d7";
const res = await fetch(
  `https://api.orbit.devotel.io/api/v1/teams/${teamId}`,
  {
    method: "PATCH",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ active: false }),
  },
);
console.log(await res.json());

Response

{
  "data": {
    "id": "team_4f9a1c2b8d3e5f60718293a4b5c6d7",
    "name": "Tier 1 Support",
    "description": "Front-line agents handling inbound chat and voice",
    "active": false,
    "created_at": "2026-09-10T09:41:12.884Z",
    "updated_at": "2026-09-10T09:47:29.540Z"
  },
  "meta": {
    "request_id": "req_teams_updated_01",
    "timestamp": "2026-09-10T09:47:29.561Z"
  }
}

Errors worth branching on

These failures cover the create, member-list, and update calls above plus the invite (POST /api/v1/teams//members) they feed. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_teamsa1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_teamsa1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape. Team writes require the team:invite grant, which built-in roles hand to owners and admins.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "name", "value": "ops+team", "expected": "a non-empty team name of 1–120 characters" }
    },
    "meta": {
      "request_id": "req_teamsb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend a corrected body instead of blind-retrying the same one.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_teamsc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

404 — Not found

  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Team not found",
      "status": 404
    },
    "meta": {
      "request_id": "req_teamsd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 404 on PATCH / DELETE means the team_* id does not exist in your workspace — re-list teams and branch on the current id rather than retrying the stale one.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`CONFLICT` (409 duplicate name)	the chosen `name` is already taken in your workspace	Branch on `error.code`. Pick a new name, or PATCH the existing team — the create step above shows the full envelope.
`NOT_FOUND` (404)	the `team_*` id is stale or foreign	Re-list and re-branch. Do not retry the id.

API Reference

All Endpoints

Worked request and response samples