How do I set up the API integration

Designed for seamless integration with external systems, the API enables automated, real-time data retrieval for custom reporting, analytics, and workflow automation.

Key Features

Comprehensive Data Access: Retrieves every issue in the system with its form, custom fields, and field values.
Real-Time Integration: Access live data as it is created and updated within the SpeakUp platform.
Enterprise-Grade Security: All API access is protected by AWS Cognito and industry-standard security protocols, ensuring data integrity and confidentiality.

2. Getting Started

Follow these steps to gain access and begin using the SpeakUp Public API.

2.1 Prerequisites

Webhooks Package Enabled — Your SpeakUp system must have the Public API package enabled
SpeakUp Administrator Role — You must be logged in as a user with administrative privileges
Service Account: The administrator will create a dedicated service account and configure the necessary permissions.
Credential Provisioning: The administrator will securely provide you with the required AWS Cognito credentials to be used in the authentication step.

3. API Endpoints

Issues Management

GET /v1/public/issues
Description: Returns all the issues across all domains in the system.

{ "id": 1, "createdAt": "2025-05-26T07:15:48.663Z", "updatedAt": "2025-07-20T00:00:51.522Z", "customId": "SUP-2024-01" }, { "id": 2, "createdAt": "2025-05-26T07:16:09.739Z", "updatedAt": "2025-07-21T10:14:44.036Z", "customId": "SUP-2024-02" }, { "id": 3, "createdAt": "2025-05-26T07:16:09.739Z", "updatedAt": "2025-10-06T00:00:22.170Z", "customId": "SUP-2024-03" } ]
GET /v1/public/issues/{id}
Description: Returns the complete detail for a single issue, specified by its unique {id}. The response is a Detailed Issue Object.
Example Response:

{ "id": 1001, "summary": "Security incident involving unauthorized access to employee data", "description": "A comprehensive security incident report detailing unauthorized access attempts to sensitive employee information through compromised credentials.", "type": "Case", "status": "Closed", "resolution": "Resolved - Security measures implemented and access controls strengthened", "assignee": "Sarah Johnson", "domain": "IT Security", "labels": ["Security", "High Priority"], "customId": "SEC-2024-001", "dueDate": "2024-12-15T17:00:00.000Z", "parentId": null, "acknowledgedAt": "2024-12-01T09:15:30.123Z", "receivedAt": "2024-12-01T09:10:15.456Z", "closedAt": "2024-12-10T16:45:22.789Z", "createdAt": "2024-12-01T09:10:15.456Z", "updatedAt": "2024-12-10T16:45:22.789Z", "issueFields": [{ "issueFieldId": 101, "fieldSystemName": "Incident Severity", "fieldLabel": "What is the severity level of this incident?", "fieldType": "option list", "fieldWidget": "dropdown", "value": "High" }, { "issueFieldId": 102, "fieldSystemName": "Affected Systems", "fieldLabel": "Which systems were affected by this incident?", "fieldType": "multiple option list", "fieldWidget": "checkbox", "value": "Database Server, Web Application" }], "issueForms": [{ "formInstanceId": 2001, "formTemplateName": "Initial Incident Assessment", "fields": [{ "fieldSystemName": "Incident Type", "fieldLabel": "What type of incident is this?", "fieldType": "option list", "value": "Security Breach" }, { "fieldSystemName": "Affected Users", "fieldLabel": "How many users were affected?", "fieldType": "number", "value": "1200" }] }, { "formInstanceId": 2002, "formTemplateName": "Technical Investigation", "fields": [{ "fieldSystemName": "Technical Analysis", "fieldLabel": "Provide technical analysis of the incident", "fieldType": "long text", "value": "Forensic analysis revealed that the attacker gained access through a compromised email account. The attack vector involved a sophisticated phishing campaign targeting employees." }, { "fieldSystemName": "Affected Systems", "fieldLabel": "List all affected systems", "fieldType": "multiple option list", "value": "Database Server, Web Application" }] }], "reportForms": [{ "formInstanceId": 3001, "formTemplateName": "Initial Reporter Information", "fields": [{ "fieldSystemName": "Reporter Name", "fieldLabel": "What is your name?", "fieldType": "short text", "value": "John Smith" }, { "fieldSystemName": "Reporter Department", "fieldLabel": "Which department do you work in?", "fieldType": "option list", "value": "IT Security" }] }, { "formInstanceId": 3002, "formTemplateName": "Incident Details", "fields": [{ "fieldSystemName": "Incident Description", "fieldLabel": "Describe what you observed", "fieldType": "long text", "value": "I noticed unusual network activity on our monitoring dashboard with multiple failed login attempts to our employee database system from unfamiliar IP addresses." }, { "fieldSystemName": "Urgency Level", "fieldLabel": "How urgent is this incident?", "fieldType": "option list", "value": "High" }] }] }

4. Data Models

The API returns different JSON structures depending on the endpoint.

4.1 Issues Object for /v1/public/issues

Field	Type	Description
id	Number	Unique numeric identifier for the issue.
customId	String	Custom string identifier for the issue.
createdAt	String	Timestamp of issue creation.
updatedAt	String	Timestamp of issue last update.

4.2 Detailed Issue Object for /v1/public/issues/{id}

Field	Type	Description
summary	String	Brief summary of the issue.
description	String	Detailed description of the issue.
type	String	Issue type (e.g., Case, Task).
status	String	Current status (e.g., Open, Closed).
resolution	String	Issue resolution (e.g., No follow-up, Done)
assignee	String	Assigned user.
domain	String	Domain associated with the issue.
labels	Array	Labels applied to the issue.
dueDate	String	Resolution due date
parentId	Number	ID of the parent issue, if applicable.
acknowledgedAt	String	Timestamp of acknowledgment.
receivedAt	String	Timestamp of receipt.
closedAt	String	Timestamp of closure.
issueFields	Array	List of Custom Field Objects.
issueForms	Array	List of Form Objects.
reportForms	Array	List of Form Objects.

4.3 Nested Objects

Custom Field Object (issueFields)

Field	Type	Description
issueFieldId	Number	Unique ID for the field instance.
fieldSystemName	String	Internal field name.
fieldLabel	String	Display label.
fieldType	String	Data type (e.g., short text, date time).
value	String	Field value.

Form Object (issueForms, reportForms)

Field	Type	Description
formInstanceId	Number	Unique ID for the form instance.
formTemplateName	String	Name of the form template.
fields	Array	Array of field objects (`fieldSystemName`, `fieldLabel`, `fieldType`, `value`).

5. Permissions and Data Scope

Permission-Based Access:
The service account must be granted the view-issue permission to retrieve issue data.
Data Scoping:
Data is automatically scoped to the business areas the service account is authorized to access.
Cross-area access requires explicit configuration by an administrator.

6. Authentication and Token Management

Access to the SpeakUp Public API requires authentication using a JSON Web Token (JWT) ID Token obtained from AWS Cognito User Pools.

The ID Token serves as the primary Bearer Token for authorizing all API calls and must be accompanied by a custom Client header.

6.1 Authentication Flow Overview

Authentication is a two-step process to obtain and use the authorization token.

Step	Action	Output	Purpose
Obtain Token	Authenticate securely using provided client credentials.	ID Token (Short-lived-10 min)	Required for API Authorization.
Authorize API Request	Include the ID Token and custom `Client` header in your HTTP request.	Successful API response.	Accessing protected public endpoints.

6.2 Obtaining the ID Token

The ID Token is obtained by securely authenticating against AWS Cognito. This token must be managed by your application to ensure uninterrupted access:

ID Token Expiry: Approximately 10 minutes.
Token Refresh: Tokens must be refreshed using the Refresh Token to obtain a new, valid ID Token before the current one expires.

Note: For the technical implementation details, including recommended client libraries (e.g., AWS Amplify) and code examples for token retrieval and refresh, please refer to the dedicated
SpeakUp: AWS Cognito Authentication Manual

6.3 Making Authorized API Calls

All requests to the SpeakUp Public API must include two essential HTTP headers:

Required Headers

Header Key	Value Format	Purpose
`Authorization`	`Bearer <YOUR_ID_TOKEN_HERE>`	OAuth 2.0 authorization using the ID Token.
`Client`	`<CLIENT_SYSTEM_NAME>`	Custom identifier required for routing and tracking your client application.

API Endpoints and cURL Examples

Below are the available GET endpoints and the required cURL structure for accessing public issue data.

Get All Issues (List) Retrieve a list of all public issues.

curl -X GET 'https://client-api.speakup.cloud/v1/public/issues' \
  -H 'Authorization: Bearer <YOUR_ID_TOKEN_HERE>' \
  -H 'Client: <CLIENT_SYSTEM_NAME>'

Get a Specific Issue (By ID) Retrieve a single public issue using its unique identifier.

curl -X GET 'https://client-api.speakup.cloud/v1/public/issues/<ISSUE_ID_HERE>' \
  -H 'Authorization: Bearer <YOUR_ID_TOKEN_HERE>' \
  -H 'Client: <CLIENT_SYSTEM_NAME>'

Placeholder Details and Client Name Lookup

You must replace all bracketed placeholders in the cURL commands:

<ISSUE_ID_HERE>: The actual unique identifier of the specific issue you want to retrieve.
<YOUR_ID_TOKEN_HERE>: Your valid and current Bearer token (ID token) used for authorization.
<CLIENT_SYSTEM_NAME>: The client system name.

How to Find the `<CLIENT_SYSTEM_NAME>`:

This name is typically derived from the subdomain of your system's URL.

Example: If your system's login URL is: https://showroom.client.speakup.cloud/login

Then your <CLIENT_SYSTEM_NAME> is showroom.

7. Technical Specifications

7.1 General Specifications

Attribute	Value
Base URL	`https://client-api.speakup.cloud/`
Data Format	`application/json`
Authentication	Bearer token in `Authorization` header
Avg. Response Time	<200ms
Request Timeout	30 seconds

7.2 Rate Limiting

Limit	Value
Rate Limit	30 requests per second
Burst Limit	60 requests per second
Max Concurrent Executions	15
Provisioned Concurrency	3

7.3 Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. When an error occurs (Status ≥400), the response body will contain a detailed JSON object providing both a human-readable message and a specific error name.

Code	Status	Description
200	OK	Request was successful.
400	Bad Request	Malformed request or invalid parameters.
401	Unauthorized	Missing or invalid access token.
403	Forbidden	Token expired or user lacks permissions.
404	Not Found	The requested resource (e.g., Issue or Channel) could not be found.
500	Internal Server Error	An unexpected server error occurred.

Error Response Examples

Here are examples of the JSON error bodies you may receive:

1. 400 Bad Request - Missing Required Parameter:

{
  "message": "Missing required parameter: issueId",
  "name": "ValidationError"
}

2. 400 Bad Request - Invalid Format:

{
  "message": "Invalid issueId format. Expected numeric value.",
  "name": "BadRequestError"
}

3. 401 Unauthorized - Missing Token:

{
  "message": "Missing access token in Authorization header",
  "name": "UnauthorizedError"
}

4. 401 Unauthorized - Invalid Token:

{
  "message": "Invalid token signature",
  "name": "InvalidTokenError"
}

5. 403 Forbidden - Token Expired:


{
  "message": "Token is expired",
  "name": "TokenExpiredError"
}

6. 403 Forbidden - Insufficient Permissions:

{
  "message": "User does not have permission to access this resource",
  "name": "ForbiddenError"
}

7. 404 Not Found - Issue Not Found:

{
  "message": "Issue with id 123 not found",
  "name": "NotFoundError"
}

8. 404 Not Found - Channel Not Found:

{
  "message": "Channel with id 456 does not exist",
  "name": "NotFoundError"
}

9. 500 Internal Server Error:

{
  "message": "An unexpected error occurred. Please try again later.",
  "name": "InternalServerError"
}

8. Security

SpeakUp ensures data protection through multiple layers:

Data Encryption: All traffic uses HTTPS/TLS.
Authentication: Managed via AWS Cognito for secure identity handling.
Authorization: Scope-based access control.
Audit Trails: Every API call is logged for full traceability.

9. Limitations and Roadmap

9.1 Current Capabilities (Phase 1)

Read-only access (GET endpoints only).
Issue-centric data model.

9.2 Future Roadmap

Planned enhancements include:

CRUD operations for Users, Groups and Group Membership .
User Invitations endpoint (POST /user-invite).
Webhooks for real-time event notifications.
Advanced Filtering options for refined data queries.