What you can do with the SpeakUp API?
The SpeakUp Public API gives external systems programmatic access to your Issue data. Use it to pull Issues into your own tools, or to update Issues in SpeakUp from a system your team already works in.
This page explains what the API can and cannot do, and points you to the right article for your task.
The Public API package must be enabled for your organisation before you can use it. Contact your Customer Success Manager if you are not sure by clicking 'Support' and 'Contact support'.
What the API can do
- Read Issue data. Retrieve Issues with their forms, custom fields, field values, report details, comments, and history.
- Update existing Issues. Change properties such as status, assignee, domain, due date, and labels, and set Issue field values.
- Download attachments. Get signed download URLs for Reporter attachments and Issue documents.
- Receive notifications. Use webhooks to have SpeakUp notify your system when an Issue is created or updated, instead of polling for changes.
- Provision Users and Groups. Use SCIM to automate account creation and removal from your identity provider.
Every update made through the API is recorded in the Issue history and attributed to the integration that made it, so there is a full audit trail.
What the API cannot do
The API works at Issue level. Two limits are worth knowing before you plan an integration:
- It does not create Issues. Issues enter SpeakUp through your reporting Channels.
- It does not send messages to the Reporter. You can read the messages on an Issue, including those from the Reporter. The API cannot post a reply into the Reporter conversation.
How access works
Access is granted through an App Integration, which an administrator creates in SpeakUp. Each App Integration has its own client ID and client secret, and its own permissions. No personal user login is involved.
Your system exchanges those credentials for a bearer token using the OAuth 2.0 client credentials flow, then sends the token on every request. Tokens are valid for 1 hour. For the exact steps, see how do I make my first API request?
You choose what each integration can reach when you create it. An integration that only produces reports should be given read only access, so it can never change data in SpeakUp.
Where to go next
| If you want to | Read this |
|---|---|
| Set up access for the first time | How do I create an App Integration and get API credentials? |
| Make your first call and confirm it works | How do I make my first API request? |
| Read Issue data | Retrieving Issues |
| Update an Issue from another system | Updating Issues |
| Get an Issue's comments or change history | Retrieving Issue activity |
| Get the messages between the reporter and case handlers | Retrieving messages |
| Download files attached to an Issue | Downloading attachments |
| Be notified when an Issue changes, rather than polling | How do I configure webhooks? |
| Automate User and Group provisioning from your identity provider | What is SCIM provisioning and when should I use it? |
| Understand an error your integration returned | API error reference |