Speakap API Reference
Welcome to the Speakap API documentation for App developers.
CUSTOM-IMPORTANT
This reference has been updated to match version v1.8.2 of our public API.
The most recent API definition is accessible here in OpenAPI format
If you have any questions regarding the contents of this documentation or have suggestions on how to improve it, please don’t hesitate to contact us. Your feedback is very welcome.
Structure and contents
This reference covers all resources and endpoints relevant to Speakap App developers, as well as some guidance on how to effectively consume our API.
Resources: Resource documentation enumerates all properties of an entity and provides examples of different representations in a response body.
Endpoints: Endpoint documentation explains how requests should be formatted and what responses can be expected. Our endpoints come in three flavors: Single resource, collection of resources and actions. The first and second are largely REST-compliant and the third type is most often an operation on one or more resources.
Authentication & authorization
Your applications need to authenticate themselves with our API. This is achieved be sending a specialized token in the Authorization header of all requests.
Besides this authentication process, we also have a fine-grained authorization system in place that protects API resources from unprivileged usage. A subset of permissions is made available for applications to enable access to certain endpoints and resources.
Applications will be audited and monitored to prevent (accidental) abuse of their privileges.
Resources
Network
Your Speakap application will run within a Speakap network. You could say that this is the top-level resource. Every enterprise using Speakap will have one or more networks where the members of said organization communicate, share and collaborate.
User
People with a Speakap account will be represented by the API in the form of a user resource. A user can either be a Speakap account or in the context of a Speakap network, the member of a network. Speakap users can be member of multiple networks and in every network they will have a distinct profile, all of which are represented by a unique user resource.
Group
Groups are a way to subdivide networks. Speakap distinguishes between basic and organization groups. Basic groups are simply one or more users teaming up in a segregated part of their network. Organizational groups exist exclusively in Enterprise Speakap and are part of a larger hierarchical structure.
CUSTOM-HINT
Not all groups are equally accessible, there are four types:
| See | Read | Share | Join | |
|---|---|---|---|---|
| 1) Public | Network Members | Network Members | Network Members | Yes |
| 2) Restricted | Network Members | Network Members | Group Members | Through Invite |
| 3) Private | Network Members | Group Members | Group Members | Through Invite |
| 4) Secret | Group Members | Group Members | Group Members | Through Invite |
Message
The message resource comes in many types. Almost everything a user shares with their network is in the form of a message: updates, comments, private messages, news items and even files. Beware of its polymorphic nature when digging through this documentation.
Alert
Speakap users will regularly receive notifications of events happening in their network. These alerts can be triggered as a result of the activity of another user (e.g. someone liked one of your updates) or as part of the notification system of the Speakap platform or any installed application.
CUSTOM-NOTE
Please note that users have control over the kind of notifications they wish to receive.