Introduction
What does the SoSafe API do?
The SoSafe API allows customers and partners like you to access important information about their SoSafe cybersecurity measures directly in software, without having to log in and view or download information manually in the Manager. With this API, you can automatically retrieve info including but not limited to:
- Employee information: Who are the users enrolled in your SoSafe awareness measures?
- Employee training progress: How far have your employees come in their cybersecurity training?
- Lesson completion: Who has finished their lessons and who still has some left to do?
- Team engagement: Get insights on how well different groups are engaging with the training.
- Risk levels & secure behavior: How good are employees at spotting simulated phishing emails and how often do they report them?
You can use this information to track user progress, create reports, or make sure that everyone is keeping up with the required training. This makes it easier to drive secure behavior.
Why does it matter for our customers and partners?
The API gives customers and partners automated access to their cybersecurity training data. The Manager and its data export are still available, but the API lets you integrate the data directly into your own workflows and manage it more flexibly.
Customers and partners often want to use SoSafe’s data for purposes such as:
- Reporting: Automating the process of pulling training data to create custom reports tailored to your specific needs.
- Integrating into internal systems: Organizations often want to feed SoSafe training data into their internal security or HR systems to get a complete view of employee training alongside other business metrics.
- Building knowledge dashboards: You can combine our data with other data you have to build custom dashboards that show training progress and identify areas that need improvement.
For partners, the API offers additional options:
- Embedding SoSafe training data into your own solutions: As a partner you can build integrations that embed cybersecurity training data into your own products or services and offer additional features to your clients.
- Joint solutions: Combine SoSafe's E-Learning data with other tools or services to create comprehensive security or training solutions for your customers.
Without the API, you have to gather the data manually in SoSafe’s interface, which makes it harder to act on it.
What is an API?
An API, which stands for Application Programming Interface, is a tool that allows two different systems or programs to talk to each other and share information. Think of it as a bridge between your company's software and SoSafe. Instead of manually logging into SoSafe to get data, the API lets your system automatically pull that data when you need it, so your system can process it the way your organization needs.
Current limitations
At the moment, the API is limited to E-Learning and Phishing Simulation data.
Technical documentation
SoSafe's REST API provides access to user, E-Learning and Phishing Simulation data from our platform, enabling integration into your systems. All data is returned in JSON format by default, allowing for easy processing and customization. By using SoSafe's APIs, you agree to our Terms of Service.
Our APIs use resource-oriented URLs, standard HTTP methods, and response codes for error handling. We provide support for integration and troubleshooting.
You will find some basic information below. For the full technical documentation, please refer to the OpenAPI specifications.
Prerequisites
To use the SoSafe API you will need:
- A running SoSafe E-Learning and / or Phishing Simulation
- Access to the SoSafe Manager API Key Management page
- If you don’t have access to this page, please check with your SoSafe contact person whether you are on the necessary package for using Analytics integrations
- Technical know-how on how to work with APIs
Base URL
The base URL for all API requests is https://connect.sosafe.de.
Authentication
To access SoSafe’s API, you authenticate with an API key and a session token:
- Generate API key: Obtain your API key from the Manager portal. This key is used to request session tokens but not for direct API access. Make sure to select appropriate scopes depending on which API requests you intend to use later.
-
Log in to get a JSON Web Token (JWT): Send a POST request to
/v1/auth/loginwith your API key in theX-Api-Keyheader. A valid request returns a short-lived JWT session token. -
Make API requests: Include the JWT in the
Authorization: Bearer <jwt>header for API access. - Token renewal: Once expired, use the API key again to obtain a new JWT session token.
For security, API requests must be made over HTTPS. Compromised API keys can be revoked in the portal.
Response format
SoSafe’s API responses are formatted in JSON. All dates and times within the responses follow the UTC (Coordinated Universal Time) standard, ensuring consistency across different time zones.
API versions
The API is versioned through the first segment of the URL path, for example /v1/users or /v2/learning/analytics. Existing /v1 endpoints keep working, new endpoints are published under /v2.
Endpoints that will be switched off are marked as deprecated in the OpenAPI specifications and return the headers Deprecation, Sunset and Link, which point to their replacement.
Response/error codes
SoSafe uses standard HTTP response codes to indicate the outcome of an API request.
- 2xx: Success
- 4xx: Client error (e.g., missing parameter, user not found)
- 5xx: Server error (e.g., internal server issue)
Error codes
- 401: Unauthorized — Invalid API key.
- 403: Forbidden — Action not permitted.
- 404: Not Found — Resource not available (e.g., user, campaign).
- 500: Internal Server Error — Try again later.
- 503: Service Unavailable — Maintenance in progress.
Security considerations
Please treat API keys carefully:
- Limit access to the key management area and the created keys to just a few employees
- Do not hardcode API keys into your codebase or check them into code repositories
- Choose scopes appropriately
- Have a key rotation process in place
- Remove unneeded keys as soon as possible
Users endpoint
The Users endpoint /v1/users allows access to a list of users associated with your account, returning relevant information such as name, email, user level, group, custom attributes, and status (enabled/disabled).
Example use cases
-
Get list of all users
Retrieve the full list of users, including detailed attributes such as their name, email, user level, group, and custom fields. -
Get list of specific users
Retrieve data for specific users with additional filtering options:- Filter by group: Return users belonging to a particular group.
- Filter by learning campaign: Return users who are part of a specific E-Learning campaign.
E-Learning endpoints
Campaigns endpoint
The campaigns endpoint /v1/campaigns/elearning allows access to the list of E-Learning campaigns running on your account. You will receive information such as the name and dates for a campaign as well as its ID, which can be useful for filtering data from the other endpoints.
Analytics endpoint (V2)
The E-Learning endpoint /v2/learning/analytics replaces the endpoint /v1/analytics/elearning and allows retrieval of user progress related to assigned training modules and campaigns. It only works for Personalized Learning campaigns. The filters are sent as JSON in the request body (POST request). After the data is returned, it can be filtered to extract specific information as required.
You can select the language of the response with the Accept-Language header. English (en), German (de) and French (fr) are available; any other language falls back to English.
What's new compared to the previous endpoint:
- All Personalized Learning data: The response contains the same data as the Personalized Learning data export, for example the learning status, overdue mandatory modules and the responsible person
- Expert filters: Filter by custom fields, user group IDs, language and user type (see below)
-
Easier to process: Values use native types (
true/falseinstead ofYES/NO,nullinstead of0or empty text),extendedDatahas the same keys in every row, and every response includes the total number of results (totalDataAmount) for pagination
If you're switching from the previous endpoint, also note these changes:
- Filters are sent in the request body instead of the query string
- Parameters were renamed:
emailIdis nowemailAddressanduserGroupis nowuserGroupName -
moduleSplitType(all/mandatory/optional) is nowisModuleSplit(-1/1/0). The default changed from all modules to mandatory modules only - IDs are returned as strings:
userId,customerId,campaignIdandgroupIdinpassedModuleData. Filters in the request body, such ascampaignId, still take numbers - The user group ID is no longer returned, only the user group name. The
groupIdinpassedModuleDatais the ID of the module's group, not the user's - Whether dynamic or non-dynamic user groups are returned now follows your account setting (
dynamicGroupDatais no longer available) - Only active users are included
- Some response fields were renamed or added. See the OpenAPI specifications for details
The following filters can be set in the request body:
-
campaignId: List of campaign IDs (mandatory). Use[0]to retrieve cumulative data across all campaigns -
isModuleSplit:-1for all modules,0for optional modules,1for mandatory modules (default) -
emailAddress: List of email addresses -
userGroupName: List of user group names -
expertFilters: Expert filterscf1tocf10(custom fields),userGroupId(user group IDs),languageandtype. Only available if your account uses extended user data-
type: Type of the recipient address.0= individual address,1= distribution list
-
-
pageandlimit: Pagination (default: page1,1000results per page)
Please refer to the OpenAPI specifications for a technical overview of the data and the corresponding format.
Example use cases
-
Get E-Learning progress of all campaigns
Retrieve cumulative progress data across all campaigns by sending[0]ascampaignId. -
Get E-Learning progress of a particular campaign
Retrieve progress for one or more specific E-Learning campaigns by sending their IDs ascampaignId. -
Get E-Learning progress of a particular user
Fetch detailed progress for a specific user by filtering onemailAddress. -
Get E-Learning progress of a group of users
Retrieve progress data for a specified group of users by filtering onuserGroupName. -
Get E-Learning progress of a particular module
Filter the returned data by module to see detailed progress for a specific training module. -
Get E-Learning progress for a custom field value
Filter the data by custom fields usingexpertFilters. The available values can be retrieved with the expert fields endpoint (see below).
Analytics endpoint (V1)
The endpoint /v1/analytics/elearning is deprecated and will be removed on November 3, 2027. Please use the endpoint /v2/learning/analytics instead (see above).
The E-Learning endpoint /v1/analytics/elearning allows retrieval of user progress related to assigned training modules and campaigns. After the data is returned, it can be filtered to extract specific information as required.
Example use cases
-
Get E-Learning progress for all users
Retrieve progress data for all users across all assigned E-Learning content. -
Get E-Learning progress of a particular user
Fetch detailed progress for a specific user. -
Get E-Learning progress of a group of users
Retrieve progress data for a specified group of users. -
Get E-Learning progress of all campaigns
Fetch progress reports across all E-Learning campaigns. -
Get E-Learning progress of a particular campaign
Retrieve progress for a specific E-Learning campaign. -
Get E-Learning progress of a particular module
Filter the returned data by module to see detailed progress for a specific training module.
Expert fields endpoint
The E-Learning endpoint /v2/learning/analytics/expert-fields allows retrieval of the custom field values available on your account. You can use them to build the expertFilters of the endpoint /v2/learning/analytics. These values come from your own data, so they aren't translated.
The data returned include:
- Customer ID
- Custom field key to use in
expertFilters(e.g.cf1) - Custom field name
- Custom field value
The optional parameters page and limit can be used for pagination. The endpoint is only available if your account uses extended user data.
Please refer to the OpenAPI specifications for a technical overview of the data and the corresponding format.
Phishing Simulation endpoints
Campaigns
The Phishing Simulation endpoint /v1/phishing-simulation/campaigns allows retrieval of a list of current and archived Phishing Simulations (also known as campaigns).
The data returned include:
- Campaign ID (which can be used to retrieve a campaign’s analytics using the endpoint
/v2/phishing-simulation/analytics(see below)) - Campaign name
- Campaign start & end date
- Campaign status:
WAITING, ACTIVE, FINISHED, PAUSED, INACTIVE, PENDING, ALLOWLISTING_PENDING, SCHEDULED - Campaign version
- Archive status (
true, false) - Analytics availability (
true, false)
Please refer to the OpenAPI specifications for a technical overview of the data and the corresponding format.
Analytics (V2)
The Phishing Simulation endpoint /v2/phishing-simulation/analytics replaces the endpoint /v1/phishing-simulation/analytics and allows retrieval of detailed phishing simulation data in the same way (see Analytics (V1) below for the available attributes), with one row per simulated phishing mail. The response uses the same export format as the analytics in the SoSafe Manager. The filters are sent as JSON in the request body (POST request). First name, last name and email address are null if the campaign doesn't allow user data in reports.
You can select the language of template names and mail status with the Accept-Language header. English (en), German (de) and French (fr) are available; any other language falls back to English.
What's new compared to the previous endpoint:
- Expert filters: Filter by custom fields, user group IDs, language and user type (see below)
-
Date range filter: Filter by the date the mail was sent (
fromandto) - Customer and campaign IDs in every row, not only the names
-
Easier to process: Values use native types (
true/falseinstead ofYes/No,nullinstead of empty text),extendedDatahas the same keys in every row, and every response includes the total number of results (totalDataAmount) for pagination
If you're switching from the previous endpoint, also note these changes:
- Filters are sent in the request body instead of the query string
-
userGroupis nowuserGroupName, anduserGroupIdis now part ofexpertFilters - IDs are returned as strings:
templateId,campaignIdandcustomerId. Filters in the request body, such ascampaignId, still take numbers - The user group ID (
organizeId) is no longer returned, only the user group name - Whether dynamic or non-dynamic user groups are returned now follows your account setting (
dynamicGroupDatais no longer available) - Some response fields were renamed, for example
firstNameis nowuserFirstNameandansweredis nowreplied. See the OpenAPI specifications for details
The following filters can be set in the request body:
-
campaignId: List of campaign IDs (mandatory). Use[0]to retrieve cumulative data across all campaigns -
fromandto: Date range (yyyy-mm-dd, inclusive) on the date the mail was sent. Both have to be provided together -
userGroupName: List of user group names -
expertFilters: Expert filterscf1tocf10(custom fields),userGroupId(user group IDs),languageandtype. Only available if your account uses extended user data-
type: Type of the recipient address.0= individual address,1= distribution list
-
-
pageandlimit: Pagination (default: page1,1000results per page)
Please refer to the OpenAPI specifications for a technical overview of the data and the corresponding format.
Analytics (V1)
The endpoint /v1/phishing-simulation/analytics is deprecated and will be removed on November 3, 2027. Please use the endpoint /v2/phishing-simulation/analytics instead (see above).
The Phishing Simulation endpoint /v1/phishing-simulation/analytics allows retrieval of detailed phishing simulation data. The available data equals the data you get in the Analytics via Exports / Download data. This means you get access to a list of all simulated phishing mails sent, with the following attributes:
- Template name & ID
- Email subject
- Recipient first and last name
- Sender name
- Language
- User group
- Mail status, including the date when it was sent
- Interaction info (opened, clicked, interacted, learned, answered and reported dates if available)
- Whether a mobile user agent was used
- Tenant & campaign name
You can use these data as a starting point to build your own KPIs if desired or emulate SoSafe’s KPIs. To find out how the latter are calculated, consult the Analytics section in our Knowledge Base.
Please refer to the OpenAPI specifications for a technical overview of the data and the corresponding format.
Expert fields
The Phishing Simulation endpoint /v2/phishing-simulation/analytics/expert-fields allows retrieval of the custom field values available for a phishing simulation (also known as campaign). You can use them to build the expertFilters of the endpoint /v2/phishing-simulation/analytics. These values come from your own data, so they aren't translated.
The parameters are:
-
campaignId: Campaign ID (mandatory). Use0to retrieve the values across all campaigns -
pageandlimit: Pagination (optional)
The custom field organize_id corresponds to userGroupId in the expert filters. The endpoint is only available if your account uses extended user data.
Please refer to the OpenAPI specifications for a technical overview of the data and the corresponding format.
Terms and conditions
The current version of the terms and conditions is available at https://support.sosafe.de/INFO/sosafe-api-terms-and-conditions.