Contact us
Contact us

Developers · Public API v1

teamside public API reference

A REST API that lets groupware, ERP and HR systems read teamside members, spaces (departments) and attendance. It is read-only: there are no create, update or delete endpoints. Outgoing webhooks and MCP for AI tools are covered too.

ProtocolHTTPS · GET · JSON (UTF-8)
AuthAPI key (X-API-Key)
Data scopeOne key = one workspace
Rate limit60 requests/min per key by default
Example URL
https://<your-domain>/serv/api/external/v1

1. Overview

ItemValue
Base URL (on-premise)https://<your-domain>/serv/api/external/v1
ProtocolHTTPS · GET only · JSON (UTF-8)
AuthAPI key (X-API-Key header or Authorization: Bearer)
Data scopeOnly the one workspace the key was issued for
Rate limit60 requests per minute per key by default

The path includes /serv. Without it you get the website's 404 page instead of the API.

There are five endpoints.

MethodPathRequired scopeDescription
GET/healthNone (no key)Service status
GET/membersmembers:readWorkspace members (guests excluded)
GET/spacesspaces:readSpaces (departments, rooms)
GET/spaces/{id}spaces:readA single space
GET/attendancesattendances:readAttendance records for a period

2. First calls

① Check status (no key)

bash
curl -s https://<your-domain>/serv/api/external/v1/health
response
{"success":true,"data":{"status":"UP","time":"2026-10-19T14:43:46.414+09:00","build":"unknown"}}

② List members (key required)

bash
curl -s -H "X-API-Key: $JC_API_KEY" \
  "https://<your-domain>/serv/api/external/v1/members?limit=50"

③ Attendance (period required)

bash
curl -s -H "X-API-Key: $JC_API_KEY" \
  "https://<your-domain>/serv/api/external/v1/attendances?from=2026-10-01&to=2026-10-31"

Put your issued key (it starts with jc_) in $JC_API_KEY. Never leave keys in code, repositories or chat.

3. Authentication

Send the key in one of two ways. If both are present, X-API-Key wins.

X-API-Key: jc_xxxxxxxxxxxxxxxx
Authorization: Bearer jc_xxxxxxxxxxxxxxxx
  • Keys always start with jc_. A Bearer value that does not start with jc_ is treated as no key and returns 401.
  • The key is shown in full only once, when issued. The server stores only an irreversible hash, so a lost key must be reissued.
  • Missing, unknown, revoked or expired keys and suspended contracts all return the same 401 (JC-4001). We deliberately do not say which.
  • /health also returns 401 if you attach a wrong key. Without a key it returns 200.
  • A key's workspace cannot be changed, and there is no parameter for a workspace ID.

4. Scopes

Each key can call only the endpoints its scopes allow. A missing scope returns 403 (JC-4003) and the message names the required scope.

scopeEndpoints
members:readGET /members
spaces:readGET /spaces · GET /spaces/{id}
attendances:readGET /attendances

Request only the scopes you need (least privilege). Adding scopes may require reissuing the key.

5. Response format

Success

json
{
  "success": true,
  "data": [ ],
  "meta": { "cursor": "bzo1MA", "hasMore": true }
}
  • List endpoints (members, spaces, attendances) return an array in data plus meta.
  • The single-item endpoint (spaces/{id}) and health have no meta.
  • Empty fields are omitted, not sent as null. Treat a missing key as "no value".
  • Fields may be added later. Ignore fields you don't know.

Failure

json
{
  "success": false,
  "error": { "code": "JC-4001", "message": "유효한 API 키가 필요합니다." }
}
  • Branch on error.code. error.message is human-readable text in Korean and its wording may change.
  • error.detail appears only when present (mainly missing or malformed parameters). Failures carry no data or meta.
  • See 10. Error codes for the full list.

6. Pagination

  • Lists are paged with limit (items per page) and cursor (next-page marker).
  • limit defaults to 50, max 200. Values above 200 become 200 and values below 1 become 1 (not an error). Non-numeric values return 400.
  • If meta.hasMore is true, pass meta.cursor unchanged as ?cursor= on the next request. When it is false you are on the last page and there is no cursor.
  • cursor is an opaque string. Do not parse or build it. A malformed cursor returns 400.
  • Ordering is fixed: members by nickname (then memberSeq), spaces by spaceSeq, attendances by attendanceSeq. Data changing between pages can cause overlaps or gaps, so for a full sync read to the end and de-duplicate by ID.
bash · read all pages (needs jq)
URL="https://<your-domain>/serv/api/external/v1/members?limit=200"
CURSOR=""
while : ; do
  RES=$(curl -s -H "X-API-Key: $JC_API_KEY" "$URL${CURSOR:+&cursor=$CURSOR}")
  echo "$RES" | jq -c '.data[]'
  [ "$(echo "$RES" | jq -r '.meta.hasMore')" = "true" ] || break
  CURSOR=$(echo "$RES" | jq -r '.meta.cursor')
done

7. Rate limits

  • The limit is requests per minute per API key. The default is 60/min and may differ per key.
  • Counting uses fixed one-minute windows (reset when the clock minute changes). Every authenticated request counts, whatever its result. Requests rejected before authentication and keyless health calls do not count.
  • Over the limit you get 429 + JC-4029 with the header Retry-After: 60. The value is always 60, not the seconds remaining.
  • On 429, wait for Retry-After; for other retries use exponential backoff.
HTTP/1.1 429
Retry-After: 60

{"success":false,"error":{"code":"JC-4029","message":"분당 요청 한도(60)를 초과했습니다."}}

8. Dates and times

  • Date parameters use yyyy-MM-dd and are read as days in Korea Standard Time (KST, UTC+9).
  • Response timestamps are ISO-8601 and always carry +09:00, e.g. 2026-10-19T09:01:00+09:00. Milliseconds may appear, so use an ISO-8601 parser rather than fixed-width slicing.

9. Endpoints

GET

/health

No key

Service status. A wrong key returns 401.

FieldTypeDescription
statusstring"UP" when healthy
timestring (ISO-8601)Current server time (KST)
buildstringIdentifier of the running build, or "unknown". The format is not guaranteed; use it for display and logs only
GET

/members

members:read

Workspace members, ordered by nickname. Guests and members who have left are excluded.

ParameterInRequiredDescription
limitqueryNo1–200, default 50
cursorqueryNometa.cursor from the previous response
FieldTypeDescription
memberSeqintegerMember ID (unique within the workspace). Same value as memberSeq in attendance
accountstringLogin account (email format). Use it to match employees in your system
namestringName
nicknamestringDisplay name in the workspace
jobGradestringJob grade (omitted if none)
spaceNamestringSpace (department) name (omitted if none)
statusstringCurrent status name as set in the workspace, in Korean (e.g. 온라인 online, 오프라인 offline, 부재중 away). New values may appear; accept unknown ones as-is

Phone numbers, addresses, location, birth dates and business details are not provided.

bash
curl -s -H "X-API-Key: $JC_API_KEY" \
  "https://<your-domain>/serv/api/external/v1/members?limit=2"
response (sample data)
{
  "success": true,
  "data": [
    { "memberSeq": 1021, "account": "[email protected]", "name": "Alex Kim",
      "nickname": "Alex", "jobGrade": "Manager", "spaceName": "Engineering", "status": "온라인" },
    { "memberSeq": 1034, "account": "[email protected]", "name": "Jamie Lee",
      "nickname": "Jamie", "status": "오프라인" }
  ],
  "meta": { "cursor": "bzoy", "hasMore": true }
}
GET

/spaces

spaces:read

Active spaces (departments, rooms), ordered by spaceSeq. Parameters: limit, cursor (as above).

FieldTypeDescription
spaceSeqintegerSpace ID
namestringSpace name
topSpaceSeqintegerParent space ID. Omitted for top-level spaces
response (sample data)
{
  "success": true,
  "data": [
    { "spaceSeq": 301, "name": "Head office" },
    { "spaceSeq": 305, "name": "Engineering", "topSpaceSeq": 301 }
  ],
  "meta": { "hasMore": false }
}
GET

/spaces/{id}

spaces:read

A single space. A non-integer id (path) returns 400. data has the same shape as a list item above.

bash
curl -s -H "X-API-Key: $JC_API_KEY" "https://<your-domain>/serv/api/external/v1/spaces/305"
response
{ "success": true, "data": { "spaceSeq": 305, "name": "Engineering", "topSpaceSeq": 301 } }

Missing spaces, deleted spaces and spaces in another workspace all return the same 404 (JC-4004), so nobody can probe for other organizations' data.

GET

/attendances

attendances:read

Attendance records with a clock-in within the period.

ParameterInRequiredDescription
fromqueryYesStart date yyyy-MM-dd (KST, from 00:00)
toqueryYesEnd date yyyy-MM-dd (KST, through end of day)
memberSeqqueryNoOnly this member. Unknown IDs return an empty list
limitqueryNo1–200, default 50
cursorqueryNometa.cursor from the previous response
  • from and to are both required. Missing or malformed values, or to before from, return 400.
  • The period can be at most 92 days, both ends included (e.g. 2026-07-01 to 2026-09-30). Split longer ranges.
  • Filtering uses the originally recorded clock-in. A record whose clock-in was corrected by an admin still appears if the original day is in range, and clockIn carries the corrected value.
FieldTypeDescription
attendanceSeqintegerAttendance record ID
memberSeqintegerMember ID
memberNamestringMember nickname
clockInstring (ISO-8601)Clock-in time; the admin-corrected value if any
clockOutstring (ISO-8601)Clock-out time. Omitted if not clocked out yet
outsidestring (HH:mm)Time spent in "out of office" status that day. "00:00" if none
missedstring (HH:mm)Time spent in "away" status that day. "00:00" if none

Attendance notes are not provided because they may contain personal information. Today's outside and missed count up to now, so they can grow on later reads.

bash
curl -s -H "X-API-Key: $JC_API_KEY" \
  "https://<your-domain>/serv/api/external/v1/attendances?from=2026-10-19&to=2026-10-19&memberSeq=1021"
response (sample data)
{
  "success": true,
  "data": [
    { "attendanceSeq": 88123, "memberSeq": 1021, "memberName": "Alex",
      "clockIn": "2026-10-19T08:57:12+09:00", "clockOut": "2026-10-19T18:03:40+09:00",
      "outside": "01:20", "missed": "00:00" }
  ],
  "meta": { "hasMore": false }
}
error examples (messages are in Korean)
{ "success": false, "error": { "code": "JC-4000", "message": "조회 기간은 최대 92일까지 가능합니다." } }

{ "success": false, "error": { "code": "JC-4000",
  "message": "요청 파라미터가 올바르지 않습니다.", "detail": "'from' 칸이 필요합니다." } }

10. Error codes

CodeHTTPMeaningTypical causeRetry?
JC-4000400Bad requestAttendance from/to missing, malformed or over 92 days; unreadable cursor; non-numeric number fieldsFix the request
JC-4001401Authentication failedMissing, unknown, revoked or expired key; suspended contract; wrong key on healthCheck or reissue the key
JC-4003403Insufficient scopeThe key lacks the endpoint's scope (message names it)Request the scope
JC-4004404Not foundMissing or deleted space, or a space in another workspaceCheck the ID
JC-4029429Rate limit exceededPer-key per-minute limit exceeded · Retry-After: 60After 60 seconds
JC-5000500Internal server errorUnexpected error (generic message only)Retry later; contact us if it persists
  • 401 never says why, and 403 means a missing scope only. Another workspace's data returns 404, not 403.
  • 4xxx codes are caller-side, 5xxx server-side. If you get a code not listed here, handle it by HTTP status and let us know.
  • Rejections by front-end infrastructure (firewall, CDN: 502, 503, 504 …) and undefined paths may not use this format. If the body is not JSON, check the URL first.

11. Receiving webhooks

teamside can send work notifications to a URL you choose. Unlike the read API above, this section is for building the receiving side.

Setup

  • Workspace owners and admins register receiving URLs in the settings screen (up to 20 per workspace). API keys cannot register them.
  • For each URL you choose the notification types (or "all"), the scope (whole workspace / specific projects / specific approval forms) and whether to hide titles. With hidden titles, titles are removed from the body entirely.
  • URLs must be reachable from the internet. Private network addresses are rejected at registration and checked again before sending. Redirects (3xx) are not followed, so register the final URL.
  • Sending must be enabled by the server operator. Confirm it is on when you start.

Delivery

  • POST · Content-Type: application/json · UTF-8 JSON body.
  • Reply with 2xx within 3 s to connect and 10 s to respond. Do slow work after acknowledging.
  • URLs with a signing secret receive X-JC-Signature: sha256=<lowercase hex>.
  • They also receive X-JC-Signature-V2: t=<unix seconds>,v1=<lowercase hex>, which includes the send time (since 2026-11-08). Check it to reject replayed requests.
  • Because of retries, the same body can arrive more than once. De-duplicate by event and alarmSeq (or occurredAt + subject).

Signature verification

The signature is HMAC-SHA256 over the raw body bytes as received (not re-serialized), keyed with your signing secret. Compare in constant time.

node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
python
import hmac, hashlib
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or '')

Verifying the timestamped signature (V2)

v1 is HMAC-SHA256 over t + . + the raw request body. Reject it if t is more than 5 minutes from now. Retries are re-signed with the retry time. X-JC-Signature is still sent, so existing verification keeps working.

node.js
const crypto = require('crypto');
// header e.g. "t=1700000000,v1=2f65…" · reject anything older than 5 minutes (300 s)
function verifyV2(rawBody, header, secret, nowSec = Math.floor(Date.now() / 1000)) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m || Math.abs(nowSec - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody, 'utf8').digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

Body (plain JSON URLs)

json · sample data
{
  "event": "approval.requested",
  "occurredAt": 1792382400000,
  "workspaceSeq": 12,
  "alarmSeq": 55012,
  "actor": "Alex",
  "recipients": [1034, 1050],
  "subject": { "requestSeq": 7001, "title": "October travel expenses", "requestType": "Expense report" }
}
FieldDescription
eventEvent key (table below). Names never change once published
occurredAtEvent time as epoch milliseconds (number)
workspaceSeqWorkspace ID
alarmSeqNotification ID (omitted for events without one)
actorDisplay name of whoever triggered the event
recipientsMember IDs who receive the notification (omitted for events without one)
subjectEvent details. Fields vary by type and may grow. Absent entirely for URLs with hidden titles

Plain JSON bodies carry no human-readable sentence. Build your own wording from the event key.

Event keys

GroupEvent keys
Approvalsapproval.requestedapproval.forwardedapproval.referencedapproval.approvedapproval.rejectedapproval.withdrawnapproval.canceledapproval.deletedapproval.commentedapproval.dueapproval.reminded
Attendance · leaveattendance.week.warnattendance.week.overvacation.promotion.urgedvacation.promotion.assigned
Inquiries · posts · surveysinquiry.createdboard.postedsurvey.openedsurvey.reopened
Meetings · seminars · resourcesmeeting.scheduledmeeting.canceledmeeting.startedseminar.scheduledseminar.canceledseminar.startedresource.bookedresource.canceled
Kanbantask.assignedtask.duetask.completed (only to URLs scoped to projects)
Membersmember.joined (only to plain JSON URLs set to "all")

member.joined goes only to plain JSON URLs set to "all", and its occurredAt is a string, not a number. Branch on event first.

Receiving in Teams or Slack

If the URL host is hooks.slack.com, *.webhook.office.com, *.environment.api.powerplatform.com or *.logic.azure.com, teamside sends a one-line notification in that service's format. The plain JSON body and signature are not used.

Failures and retries

ResponseHandling
2xxSuccess
408 · 429 · 5xx · 3xx · connection failure · timeoutRetry
Other 4xxGive up immediately

Up to 5 attempts in total (1 + 4 retries) with growing intervals (up to about 4 minutes). Deliveries that fail all 5 attempts are not resent. Notifications are not queued while a URL is turned off.

12. AI tools (MCP)

AI tools such as Claude, ChatGPT and Gemini can use teamside as MCP tools with the same API key. No extra server: just one URL.

ItemValue
URLhttps://<your-domain>/serv/api/external/v1/mcp
TransportMCP Streamable HTTP · stateless
AuthThe API key from section 3 (Authorization: Bearer jc_… or X-API-Key)

Only read tools within the key's scopes are listed: list_members · list_spaces · get_space · list_attendances. The same rules apply as for REST (cursor, limit, 92 days), and each MCP request counts once toward the rate limit.

claude code
claude mcp add --transport http joycollab https://<your-domain>/serv/api/external/v1/mcp \
  --header "Authorization: Bearer ${JC_API_KEY}"

Member and attendance data read through AI tools is passed to the AI provider you choose. Check your internal privacy rules (member consent, processing agreements) first.

Connection examples for each tool come with the onboarding consultation. MCP is off by default; each company decides whether to turn it on.

13. Getting a key

Workspace owners and admins can create and revoke keys themselves in teamside under Settings › Admin › “Integration keys”. Choose what each key can read (section 4); the full key is shown only once, when created. Up to 10 active keys per workspace.

If you can't create one yourself or need a different rate limit, ask us and include:

  1. The workspace to connect (name or URL)
  2. The scopes you need (section 4)
  3. Expected volume (calls per minute, sync interval)
  4. Whether you want an expiry date
  5. Whether it will be used by AI tools (MCP) — if so, confirmation that your privacy rules have been checked

If a key is lost or may have leaked, tell us right away; we will revoke it and issue a new one. For on-premise installations, ask your installation contact.

Need help with scopes or call volume? Just ask.

API key & integration inquiry

14. Troubleshooting

SymptomCheck
Website 404 HTML returnedWhether /serv is missing from the URL
401Typos, the jc_ prefix, the space after Bearer, expiry, revocation. Don't attach a wrong key to health
403Request the scope named in the message
400 on attendancefrom/to format, within 92 days, to ≥ from
404 on a spaceWhether the space belongs to this key's workspace
429Per-minute limit exceeded. Retry after 60 seconds
Duplicates or gapsData changed between pages. See section 6

Last updated 2026-11-06 · API v1