Common Services API (2.21.0-integration.1)
This document is intended for SSG developers who need applications to interact with backend services and data. It explains basic concepts of SchoolStatus and the API itself. It also provides an overview of the different API supported functions.
- Some way to hit an API endpoint and receive responses. We’re aware that various organizations within SchoolStatus have different technical stacks, and so we advise that you use whatever your preferred library is for API connections.
- An API Key. For now, these can be requested from the Platform team, but we will move this functionality over to either DevOps or IT management at some point.
- A phone number to send/receive SMS from - for now, this should come from Twilio, but we will add support for other providers in the future.
- A callback URL - somewhere we can send updates and information about inbound messages to.
- Familiarize yourself with the core concepts of the JSON (JavaScript Object Notation) data format. JSON is a common, language-independent data format that provides a simple text representation of arbitrary data structures.
This Quickstart will teach you how to do send and recieve text and calls using the Contact Channel API. In this Quickstart, you will learn how to:
- Get an API Key to Authenticate with Shunkan-Ido
- Set up your development environment to send and receive messages
- Send your first SMS
- Receive inbound text messages
- Reply to incoming messages with an SMS
- Start your first call.
You can find all this at Platform Wiki.
The API uses standard HTTP status codes to indicate the success or failure of an API request.
| Code | Meaning |
|---|---|
| 200 | OK |
| 201 | Created |
| 204 | No Content |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 422 | Unprocessable Entity |
| 500 | Internal Server Error |
Most of the error codes include a JSON response body that contains more information about the error.
{
"error": {
"code": 0,
"message": "string",
"detail": "string"
}
}
the code field is an integer that indicates the type of error that occurred. the message field is a human-readable string that describes the error. the detail field is a human-readable string that provides more details about the error.
We try to catch most of the errors from the first API call and return them inmediately. But sometimes, we need to notify the client about an error that happened in the middle of the process.
For this, we have a webhooks system that allows you to receive notifications about the status of your requests. The payload you get depends on the type of request you made, you can find more information about the different types of requests in the Webhook Events section.
2.21.0-integration.1 (2026-10-27)
- [COMM-2753] reuse Twilio connections for announcement SMS (623de3a)
- add twilio machine detection to voice announcements refs: II-226 (5be55c8)
- ii-249 add indexes for the message_sid columns on messages and announcement messages (ca0be56)
- refs #comm-702 #comm-2052 working code (9dff9dd), closes #comm-702 #comm-2052
2.21.0-integration.1 (2026-10-27)
- [COMM-2753] reuse Twilio connections for announcement SMS (623de3a)
- add twilio machine detection to voice announcements refs: II-226 (5be55c8)
- ii-249 add indexes for the message_sid columns on messages and announcement messages (ca0be56)
- refs #comm-702 #comm-2052 working code (9dff9dd), closes #comm-702 #comm-2052
2.20.0 (2026-10-06)
- assign voice integrity and cnam to auto-provisioned numbers (d4f4109)
2.19.0 (2026-09-18)
- keep a deactivated shared service selected on the customer form (30f6994)
2.18.0 (2026-04-23)
- modified max length for sms body size (34cbaeb)
2.17.0 (2026-02-05)
- webhooks: implement webhook queue priority refs II-283 (93b5e07)
2.16.0 (2026-02-05)
2.16.0 (2026-01-30)
2.15.0 (2026-01-14)
2.14.2 (2026-01-05)
- allow shared messaging services in regions without numbers to set lat/long refs II-229 (f1f79dd)
2.14.1 (2026-01-05)
- send voice call for announcement messages when the recipient cannot receive SMS (4d9c82e)
2.14.0 (2025-12-16)
- II-250 Index for scheduled message lookup (bf9ff11)
2.13.0 (2025-12-11)
2.13.0 (2025-12-09)
- add twilio machine detection to voice announcements refs: II-226 (53d59e3)
2.12.2 (2025-12-05)
- refs #comm-702 #comm-2052 - add retries for conversation lookup to handle race conditions while doing conversation create (c6b7672), closes #comm-702 #comm-2052
2.12.1 (2025-10-24)
2.12.0 (2025-10-02)
- add status webhooks to voice and sms announcements refs COMM-1569 (ebed6b7)
- add status webhooks to voice and sms announcements refs COMM-1569 (dd7b5b9)
- add Verify active numbers base setup (c3d33ea)
- add voice announcement endpoints refs COMM-1567 (ccbbdd6)
- add voice announcement endpoints refs COMM-1567 (e1ddc06)
- announcements: add inbound reply webhooks refs COMM-1623 (8e0459e)
- move announcement number logic fro active admin customers to messaging services refs: II-97 (96134c7)
- prevent double messaging service on customer (9deb59c)
- remove buttons to migrate customers and auto provision announcement number refs: II-99 (856ec68)
- track errors for invalid voice calls refs: COMM-1571 (6e4b20d)
2.11.0-staging.1 (2025-09-25)
- add duration column to voice announcements refs: II-102 (cacb1eb)
- add status webhooks to voice and sms announcements refs COMM-1569 (84ec974)
- add status webhooks to voice and sms announcements refs COMM-1569 (ebed6b7)
- add status webhooks to voice and sms announcements refs COMM-1569 (dd7b5b9)
- add Verify active numbers base setup (c3d33ea)
- add voice and voice call views in active admin refs: COMM-1699 (0f82af6)
- add voice announcement endpoints refs COMM-1567 (db2e3df)
- add voice announcement endpoints refs COMM-1567 (ccbbdd6)
- add voice announcement endpoints refs COMM-1567 (e1ddc06)
- add webhooks panel to announcement message activeadmin (7f9cc03)
- announcements: add inbound reply webhooks refs COMM-1623 (b983c6d)
- announcements: add inbound reply webhooks refs COMM-1623 (8e0459e)
- move announcement number logic fro active admin customers to messaging services refs: II-97 (96134c7)
- prevent double messaging service on customer (9deb59c)
- remove buttons to migrate customers and auto provision announcement number refs: II-99 (856ec68)
- track errors for invalid voice calls refs: COMM-1571 (03de6ae)
- track errors for invalid voice calls refs: COMM-1571 (6e4b20d)
2.10.0 (2025-08-29)
- add bearer edit page (30e6b4c)
2.9.0 (2025-08-14)
- prevent double messaging service on customer (59a89d3)
2.8.0 (2025-08-07)
- summer reset messaging service numbers (220eb7f)
2.7.0 (2025-07-14)
- add ResetNumbersPairingService for global_customer_id (0e694f6)
2.6.0 (2025-06-23)
- add Verify active numbers base setup (960de7a)
- deactivate paring when provider number is removed (bbbfb30)
2.5.1 (2025-06-11)
- refs #comm-1620 add notify_event call for all updates (a8fb934), closes #comm-1620
- refs #comm-1620 fix missing status update metadata (c0e1859)
2.5.0 (2025-06-02)
- add more fields to the annoncement message blueprint COMM-1599 (20f00b6)
2.4.1 (2025-05-21)
- fix duplicate voicemails refs COMM-1462 (2301011)
2.4.0 (2025-05-20)
- add RebalanceUnusedTwilioNumber to MessagingService (1b77c0a)
2.3.1 (2025-05-09)
- send conference participant call webhooks refs COMM-1431 (984230d)
2.3.0 (2025-04-22)
- provider numbers dashboard (88ca65e)
- Scheduled Messages from blocked senders are being Delivered (b147e12)
2.2.3 (2025-04-21)
- start call recording on answer refs COMM-1410 (2df657b)
2.2.2 (2025-04-10)
- add recording message to return call refs TPL-68 (9ead322)
2.2.1 (2025-04-09)
- accept moderator_id in P2P calls and check for missing conversation refs TPL-58 (bb1823d)
2.2.0 (2025-04-08)
- add data migration interface (38356af)
2.1.2 (2025-04-04)
- conversations documentation, refs: COMM-1353 (a923eb5)
2.1.1 (2025-04-02)
2.1.0 (2025-04-01)
- add call update endpoint and return call metadata refs COMM-1330 (0271783)
2.0.0 (2025-03-24)
- calls: The V1 endpoint creates a conversation from the provided conversastion params (ex. client_conversation_id, global_customer_id, etc.) if one does not already exist and the params are valid. This does not make sense for how voice tokens are used for incoming calling. In incoming calling, a Twilio device must be initialized on app load, so it is not associated with any particular conversation. Since the V2 endpoint removes the side effect of creating a conversation, it is a breaking change.
2.0.0 (2025-03-24)
- calls: The V1 endpoint creates a conversation from the provided conversastion params (ex. client_conversation_id, global_customer_id, etc.) if one does not already exist and the params are valid. This does not make sense for how voice tokens are used for incoming calling. In incoming calling, a Twilio device must be initialized on app load, so it is not associated with any particular conversation. Since the V2 endpoint removes the side effect of creating a conversation, it is a breaking change.
- calls: adds a V2 endpoint for creating Twilio Voice SDK access tokens (b4c4ea8)
1.31.1 (2025-02-26)
- recipients: unique numbers insert_in_batches for recipients (650b384)
1.31.0 (2025-02-18)
1.30.3 (2025-01-14)
1.30.2 (2025-01-13)
- uniq list of recipients before inserting when enqueuing mms (780784c)
1.30.1 (2025-01-10)
1.30.0 (2025-01-09)
- add TwilioWebhookUpdate consumer handler (796dca9)
1.29.0 (2025-01-08)
- provider_number panel (bd9ca1d)
1.28.0 (2025-01-07)
- handle lookup errors with internal_status and send notification (c65bd82)
1.27.0 (2024-12-18)
- Update to latest datadog gem. We updated to version 2.8 so that we can get profile allocation data in DataDog. (bbc16c5)
1.26.0 (2024-12-13)
1.25.1 (2024-12-11)
- COM-1005 remove e164 validation error (648e927)
1.25.0 (2024-12-10)
- add conversations associations aa view (d2cb6b8)
- add participant associations aa view (04223a3)
- add webhooks associations aa view (bb289f4)
- video_calls: add association panels for video call participants in activeadmin (f40b048)
- video_calls: add association panels for video calls in activeadmin (070b97a)
1.24.0 (2024-12-09)
1.23.0 (2024-12-04)
1.24.0 (2024-12-04)
- phone voice service twiml response and callback url (6e90d0c)
1.23.0 (2024-12-04)
- [COMMS-973] Add E.164 validation to receiver numbers for messages (8f5f340)
- [COMM-935] eliminate machine detection on non-moderator calls to solve endless hold music problem (6521f97)
1.22.0 (2024-11-21)
- COMM-937 Validate that the client_conversation_id and application_name combination is unique (b3b5256)
1.21.0 (2024-11-19)
1.20.1 (2024-11-14)
- typo in method call for creating customers (f1d2f4c)
1.20.1 (2024-11-14)
- typo in method call for creating customers (f1d2f4c)
1.20.0 (2024-11-14)
- new announcements feature payloads input/output (cd919c8)
- refs #comm-909 add announcements to activeadmin views (4da2adf), closes #comm-909
- refs #comm-909 add recipient activeadmin view (24a9299), closes #comm-909
- refs #comm-910 only use non-announcement numbers in magic source (cbf0ac3), closes #comm-910
- refs #comm-910 update announcement number from ActiveAdmin (8d4797e), closes #comm-910
1.19.0 (2024-11-12)
- customize active admin authentication logic to ignore devise and use one login COMM-450 (cfe0a71)
1.18.1 (2024-11-07)
- check for blocked status on scheduled messaging refs COMM-894 (802f070)
1.18.0 (2024-11-07)
- messages dashboard (e454467)
1.17.0 (2024-11-01)
1.16.0 (2024-10-31)
- allow delete and update TwilioNumber in AA (1980d95)
1.15.1 (2024-10-30)
1.15.0 (2024-10-24)
- alter incoming calling menu (f1179f6)
- video_calls: video Call Domain Action End is trying to end a call that is already expired (408b17b)
1.14.0 (2024-10-09)
- Add mock-twilio gem 1.0.0 (1372e68)
- Add mock-twilio integration status endpoints (889e895)
- Add mock-twilio integration toggle (02d8614)
- Add Switchable mock and real data (3e8afe5)
- adding credentials for one login production env (2fd96ff)
- adding one login credentials for staging environment (cd9bd48)
- set up mock schema data (07cf4d2)
- move tables from common_services to public schema (6bd842d)
1.13.0 (2024-10-01)
1.12.0 (2024-09-26)
- fix video call webhook type typo refs COMM-832 (8814830)
1.11.1 (2024-09-19)
1.11.0 (2024-09-19)
- migration for customers dedicated (e713b1c)
1.10.0 (2024-09-16)
1.9.0 (2024-09-10)
- add automatic machine detection result as attribute on calls object refs COMM-525 (#401) (a62facf)
- Add staging to recordings CF url formation (#385) (cd53c75)
- Set new integration DB (#397) (228b3e5)
- set state code in phone numbers refs: #COMM-803 (#399) (1c81fb9)
- shunkan ido translation of classic number pairings COMM-743 (#386) (97fa42a)
1.8.0 (2024-08-26)
- Add classtag domain callback_url migration to connect url (#382) (ca4400f)
- fetch numbers from state related with messaging service k12 (#394) (7e74d6a)
- refs #comm-752 enforce maximum call length (#376) (243e2c2)
- rexml CVE-2024-43398 (#396) (5e22106)
- use tick to execute scheduled tasks refs: #COMM-772 (#390) (b6c7058)
1.7.0 (2024-08-16)
- adding new end point to receive webhook request from lambda fun… (#368) (32fdc4a)
- comm-441 Video Call Recording functionality (#299) (0fc253a)
- refs #comm-753 handle session key parameter when creating video call participant (#371) (5568289)
- update docker-compose to enable external access to local kafka cluster (#378) (8b733c9)
1.6.0 (2024-07-25)
- Add virtual_host option s3 recordings url formation (#365) (6150387)
- db structure for customers table and K-12 refs: COMM-722 (#366) (4caadea)
- fix message_body string OPT_OUT case-insensitive (#367) (44f6621)
- refs #comm-616 add caller ID to voicemail webhooks (#361) (cc2a162)
- upgrade twilio-ruby and mock-twilio (#363) (b53ef77)
1.5.0 (2024-06-24)
- add mock twilio gem (#353) (57e9c01)
- add mock-twilio 0.2.0 - Webhooks::Messages.trigger (#354) (57b8f56)
- add Mock::Twilio::Client (#348) (57e9c01)
- refs: #comm-546 automatically sync twilio numbers (#342) (0ed868e)
- save error_code and set error_description from webhook updates in messages refs: #COMM-566 (#350) (e1fb127)
- switch to mms type if sms > 160 characters refs: #COMM-594 (#359) (24db97b)
1.4.0 (2024-05-21)
1.3.0 (2024-05-20)
- refs #comm-550 edit conversation by client_conversation_id (#343) (282d715)
- refs #comm-550 edit conversation by global_id (282d715)
- refs #comm-550 edit conversation by internal_conversation_id (282d715)
- refs comm-517 change default welcome message (#335) (a572b3f)
- remove 160 characters validation for SMS body refs: #COMM-558 (#344) (18ce239)
1.2.2 (2024-05-09)
1.2.1 (2024-05-06)
- refs #comm-492 fix: create voicemail records on webhook (151d3b0)
1.2.0 (2024-05-03)
1.1.0 (2024-04-25)
- adds the ability to play a welcome message to call participants on a conference call (53bc624)
- comm-412 zoom webhook handler (#288) (9eeb5d0)
- comm-436 welcome messages for conference calling. (#292) (53bc624)
- document callback_url logic refs: #COMM-483 (#315) (a2abef4)
- github release action using release-please-action refs: #COMM-489 (1e2b637)
- github release action using release-please-action refs: #COMM-489 (d2a9fcf)
- implement get endpoint for D2P call recording by providing the Call UUID refs: #COMM-455 (#296) (5872637)
- Improve transcription documentation refs: #COMM-443 (#302) (0aea719)
- refactor documentation for conference calls and direct calls in swagger refs: #COMM-460 (#306) (c0331c0)
- refs #comm-434 configurable welcome message for direct calls (#287) (8cfc2ae)
- refs #comm-458 messaging service endpoints (#300) (830135f)
- refs #comm-463 add data migration to delete data in local/integ… (#304) (6d5cdc4)
- save webhook payload in DB and show in activeadmin refs: #COMM-431 (826c768)
- save webhook payload in DB and show in activeadmin refs: #COMM-431 (#289) (826c768)
Servers
https://shunkan-ido-staging.schoolstatus.com
https://shunkan-ido-integration.schoolstatus.com
https://shunkan-ido-production.schoolstatus.com
http://localhost:3000