Contact us
Contact us

Use cases · Public API

Putting the public API to work

Attendance records into payroll, approval notifications into chat channels, and your organization's status into an AI conversation. Here are three workflows you can build with teamside's REST API, webhooks and MCP, laid out with the real endpoints and setup steps.

All names, companies and numbers on this page are sample data for illustration.

CASE 01

Send attendance records to your payroll system

If your staff clock in on teamside but payroll is calculated in another system, one script can replace the monthly routine of downloading attendance and re-typing it.

Flow

  1. Runs on a set dayA scheduled job on your server (cron, Task Scheduler) runs the script.
  2. Match membersGET /members pairs member numbers with login accounts.
  3. Fetch last monthGET /attendances pulls the whole month, page by page.
  4. Write a fileClock-in, clock-out, out-of-office and away time per person and day go into a CSV.
  5. Review, then importCheck only the "needs review" rows and import into payroll.

What you need

  • A workspace owner or admin creates a key under Settings › Admin › "Integration keys".
  • Two scopes are enough: members:read and attendances:read. Leave everything else off.
  • The key is shown only once, when it is created. Don't put it in the script; store it in an environment variable on the server (e.g. JC_API_KEY).

Values you get

ValueMeaningHow payroll might use it
accountLogin account (/members)The key for matching employees in payroll
clockIn · clockOutClock-in and clock-out times (KST, ISO-8601)Working days and time on site
outsideTime spent "Out of office" that day (HH:mm)Field-work allowances, trip checks
missedTime spent "Away" that day (HH:mm)Reviewing working hours

Sample script

Python 3.11 or later, standard library only. Based on the day it runs, it fetches the 1st through the last day of the previous month and writes attendance-YYYY-MM.csv.

python · last month's attendance → CSV
import csv, datetime as dt, json, os, urllib.parse, urllib.request

BASE = "https://<your-domain>/serv/api/external/v1"
KEY = os.environ["JC_API_KEY"]  # keep the key in an environment variable, not in code


def get_all(path, params):
    """Walk every page and yield each item in data."""
    params = {**params, "limit": 200}
    while True:
        url = f"{BASE}{path}?{urllib.parse.urlencode(params)}"
        req = urllib.request.Request(url, headers={"X-API-Key": KEY})
        with urllib.request.urlopen(req, timeout=30) as res:
            body = json.load(res)
        yield from body["data"]
        if not body["meta"]["hasMore"]:
            return
        params["cursor"] = body["meta"]["cursor"]


last = dt.date.today().replace(day=1) - dt.timedelta(days=1)  # last day of previous month
first = last.replace(day=1)
account = {m["memberSeq"]: m["account"] for m in get_all("/members", {})}

seen = set()
with open(f"attendance-{first:%Y-%m}.csv", "w", newline="", encoding="utf-8-sig") as f:
    w = csv.writer(f)
    w.writerow(["account", "name", "date", "in", "out", "on_site_min", "outside", "away", "needs_review"])
    for a in get_all("/attendances", {"from": first.isoformat(), "to": last.isoformat()}):
        if a["attendanceSeq"] in seen:  # rows repeated while paging
            continue
        seen.add(a["attendanceSeq"])
        cin = dt.datetime.fromisoformat(a["clockIn"])
        cout = dt.datetime.fromisoformat(a["clockOut"]) if "clockOut" in a else None
        stay = int((cout - cin).total_seconds() // 60) if cout else ""
        acct = account.get(a["memberSeq"], "")
        why = "no clock-out" if not cout else ("not in member list" if not acct else "")
        w.writerow([acct, a["memberName"], f"{cin:%Y-%m-%d}", f"{cin:%H:%M}",
                    f"{cout:%H:%M}" if cout else "", stay, a["outside"], a["missed"], why])
Output CSV (sample data)
account,name,date,in,out,on_site_min,outside,away,needs_review
gildong.hong@example.com,Gildong,2026-10-19,08:57,18:03,546,01:20,00:00,
chulsoo.kim@example.com,Chulsoo,2026-10-19,09:04,,,00:00,00:00,no clock-out
cron · 4 a.m. on the 3rd of each month
0 4 3 * * cd /opt/jc-payroll && JC_API_KEY=... python3 export_attendance.py

Each page holds up to 200 rows, so a month in which 100 members each worked 22 days (2,200 rows) takes 11 attendance calls plus 1 member call — well within the default limit of 60 requests per minute per key.

Good to know

  • Time on site is not working time. Break deductions, overtime/night/holiday premiums and leave are not provided by the API. Apply your company's rules in the payroll system.
  • Only days with a clock-in appear. Days without a clock-in, such as absences or leave, are not in the list.
  • A clock-in time corrected by an admin comes back as the corrected value. Run the script after attendance has been finalized (e.g. on the 3rd, as above) to include corrections.
  • Records of people no longer in the member list (e.g. deleted accounts) have an empty account and are marked for review.
  • The script only reads, so re-running it never changes data in teamside. If it fails, check the error and run it again.
  • Attendance notes (memos) are not exported through the API because they may contain personal information.
CASE 02

Approval notifications in Teams or Slack

If your team chats in Teams or Slack but handles approvals in teamside, you can post a one-line notification to a team channel so approval requests don't get missed. It takes admin settings only — no development.

What appears in the channel

Example screen. The channel name, times and document title are sample data; the sentence format is real. Notification sentences are currently sent in Korean.

Setup steps

  1. Create a channel URLIn Slack, use "Incoming Webhooks" and pick a channel. In Teams, use the channel's "Workflows" → "Post to a channel when a webhook request is received".
  2. Register the destinationPaste the URL into the "Notification forwarding" card on the Settings › Admin tab. Slack or Teams is detected from the URL.
  3. Choose scope and eventsPick a scope ("All" or "Approval form") and the approval notifications to send.
  4. Test, then saveUse "Send test" to confirm a test message reaches the channel, then save.

Example setup

Each workspace can register up to 20 destinations, so each channel can have its own scope and notifications.

Channel (example)ScopeNotificationsTitle
#approvalsAllRequest approval.requested
Your turn approval.forwarded
Due soon approval.due
Shown
#financeApproval form: Expense reportApproved approval.approved
Rejected approval.rejected
Hidden

There are ten approval notifications: requested, your turn, referenced, approved, rejected, withdrawn, canceled, deleted, commented and due soon. Attendance (52-hour week warning/exceeded), meeting, resource booking, board and survey notifications can be chosen on the same screen. The full list is in section 11 of the reference.

Good to know

  • Only owners and admins can set it up.
  • A one-line notification does not say whose turn it is. Splitting channels by team or form makes the audience clear.
  • Anyone who knows the channel URL can post to that channel. Don't share it outside.
  • If delivery fails, it is tried up to 5 times in total with growing intervals. Destinations are not turned off automatically after repeated failures, so check the status on screen now and then.
  • While a destination is switched off, notifications are not queued; sending resumes with notifications after you switch it back on.
  • Teams' older "connector" URLs have been retired by Microsoft. Create new URLs from "Workflows".
  • To receive notifications on your own server, register a plain JSON URL and verify the X-JC-Signature signature (reference section 11).
  • On an on-premises installation, the teamside server must be able to reach the internet at the Slack or Teams URL. If outbound traffic is blocked, open just those addresses.
CASE 03

Ask an AI about attendance and your org

Instead of opening several screens and cross-checking tables, ask something like "Who hasn't clocked in yet today?" in an AI chat, and the AI reads teamside data to answer. It only reads; it never changes data.

An illustrative conversation (not real customer data). Which tools the AI calls depends on the question; the AI chooses.

Two ways to connect

"AI service connection" — each member

Connect from the web app of an AI service such as Claude.ai using a connector · no development

  • Reads with the connecting person's own permissions. What they can't see in the app, the AI can't see either.
  • Member and space (department) lists, plus attendance records if allowed
  • If an admin turns them on: my tasks list_my_tasks · approvals list_approvals · contacts list_contacts · company board list_board_posts
  • Member email addresses are not shared.

API key — company-wide

Add the URL and key to Claude Code, the Claude API, the OpenAI API, Gemini CLI, Cursor and similar tools

  • Uses the same "Integration keys" as case 01. Only the scopes turned on for the key show up as tools.
  • Members list_members · spaces list_spaces · get_space · attendance list_attendances
  • Reads the whole company, which suits internal analysis and report automation. With a key, the member list includes login accounts.

Connection steps

"AI service connection"

  1. An admin turns it onIn the "AI service connections (company setting)" card on the Settings › Admin tab, turn it on and choose the allowed AI services, whether attendance may be read, and the readable items. You confirm once what information will be shared.
  2. Share the URLCopy "For members — connector URL" from the same card and send it to members.
  3. A member connectsIn the AI service's add-connector screen (on Claude.ai, "custom connector"), enter the URL and sign in with their teamside account.
  4. Allow on the consent screenCheck the workspace and the information to be read, then press "Allow".

On an on-premises installation this feature is off at first, and each company decides whether to turn it on. For an AI service's web app to connect, the teamside server address must be reachable from the internet. If your server is internal-only, use the API key method below.

API key (e.g. Claude Code)

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

Connection steps for other tools and the MCP rules are in section 12 of the reference.

Safeguards

ConcernSafeguard
Could the AI change data?All tools in this case are read-only. There are no create, update or delete tools.
Could it see what it shouldn't?"AI service connection" applies the connecting person's own permissions. Approvals come without body, attachments or amounts, and documents marked "secure" never appear. Contacts come without email or address.
Could a connection linger?A connection ends after 30 days unused or 90 days in total, and also when the password changes. Members ("Connected AI services") and admins ("AI connections") can see connections and the last 30 days of calls, and disconnect immediately.
Could someone connect without us knowing?A connection exists only after the person signs in and presses "Allow", and only AI services the admin allows can connect.

Information read through an AI tool is sent to and processed by that AI service's operator. Before turning this on, check your internal rules for personal data (notice and consent of members, processing agreements, etc.).

Learn more

  • Public API reference — parameters, responses, error codes and webhook signature verification for each endpoint

Questions about connecting with your company's systems? Feel free to contact us.

Integration inquiry

Last updated 2026-11-07 · API v1