- Overview
- Account Syncing
- Getting Started
- User Onboarding
- User ID Management
- User Updates
- Suspend / Unsuspend User
- Targets
- Divisions
- Examples
- Rate Limits
- Throttling Recommendations
Overview
The Dynamic Signal team is involved in every customer API implementation to ensure best practices, quality assurance, and to solve each business need in a scalable format.
Many customers use Dynamic Signal REST APIs to complete Account Syncing – Passing the member’s metadata (e.g., location, department, role, content preference, etc.) from the existing system of record to Dynamic Signal’s platform.
Account Syncing
The Dynamic Signal team works with your business stakeholders to structure how employee data will look on our platform and meet your communication and segmentation needs.
As a Global Administrator, you have access to the API settings in your Dynamic Signal dashboard. In addition to integrating your SAML 2.0 single sign-on provider or allowlisting your email domain, you can register users on the Dynamic Signal platform directly through the APIs at API Reference - Registration.
You can also use Dynamic Signal APIs to update member properties (such as department, role, content preferences, etc.) which are frequently maintained in systems such as Active Directory, Workday, and others. See API Reference - User Management.
Getting Started
- Go to the API page at https://<sample.dynamicsignal.com>/manage/api* to get the bearer token.
- Use this bearer token to make server authenticated calls. It should be included in the header of your requests.
- Use the following sample for request headers:
- Host:<sample.dynamicsignal.com>
- Authorization:Bearer <insert bearer token here>
- Content-Type:application/json
* Replace sample.dynamicsignal.com with your Community’s URL when retrieving your bearer token.
User Onboarding
Creating new users:
POST https://<sample.dynamicsignal.com>/v1/manage/preregister
Creates a new user in the preregistered state. You can also use this endpoint to add user properties like user tags, attributes, targets, and divisions. You can use flags like sendInvitationEmail, notificationsDefault, privileges in the request body to change default settings for users when creating new accounts.
You can pull user properties from your HRIS system and add them in the request body to assign those data fields to users on the Dynamic Signal platform. Data fields can map to user properties like targets, tags, and divisions on the Dynamic Signal platform. You trigger this action when a new user is created in your HRIS.
POST https://<sample.dynamicsignal.com>/v1/batch/manage/preregister
User ID Management
Dynamic Signal User IDs are needed when making calls to update users in the platform. Therefore, it is important to maintain a master set of mappings between the unique User ID in Dynamic Signal and your HRIS system. This master set of mappings should be stored and maintained on your end in a solution, such as a database table that can be referenced when making API calls.
Capturing the Dynamic Signal User ID is generally done by the response when making the call to create a user in the Dynamic Signal platform. However, if you need to make subsequent calls to get a Dynamic Signal User ID then the following endpoints can be used:
POST https://<sample.dynamicsignal.com>/v1/manage/users/email
This endpoint allows you to get the Dynamic Signal User ID based on the user’s email address in the Dynamic Signal platform.
POST https://<sample.dynamicsignal.com>/v1/manage/users/externalssoid
This endpoint allows you to get the Dynamic Signal User ID based on the user’s SSO ID in the Dynamic Signal platform.
User Updates
Updating user properties:
DELETE https://<sample.dynamicsignal.com>/v1/manage/users
PATCH https://<sample.dynamicsignal.com>/v1/manage/users
PUT https://<sample.dynamicsignal.com>/v1/manage/users
Allows you to update existing user properties. You can use these endpoints to delete/add/replace values from a user account. This allows you to update user divisions, tags, targets, notification settings, and assign managers to create a hierarchy on the platform. These calls can be more adhoc, or can be triggered by changes to users in your HRIS system.
Suspend / Unsuspend User
Suspend User
POST https://<sample.dynamicsignal.com>/manage/api/v1/manage/user/{id}/suspend
Unuspend User
POST https://<sample.dynamicsignal.com>/manage/api/v1/manage/user/{id}/unsuspend
Suspend and unsuspend calls are used only for individual accounts, and cannot be used as a batch call. These calls are triggered when employees are removed from your HRIS system, or based on other flags set to identify employees that are no longer with the organization. The {id} in these calls refers to a unique ID of a user on the Dynamic Signal platform.
Targets
Content Targeting is a powerful tool that helps Managers control the content that members have access to.
Get targets:
GET https://<sample.dynamicsignal.com>/v1/targets
This endpoint allows you to get a list of all targets and target information from the community. It is important to maintain a master set of target IDs and attributes to reference when assigning or updating targets to users in the platform.
Create targets:
POST https://<sample.dynamicsignal.com>/v1/manage/targets
You can use this endpoint to create a new target in the community. This endpoint allows you to add new targets for what content and communications the user should be receiving. Once a new target is created in the community, you will receive the unique ID of the target in the response.
Update targets:
PUT https://<sample.dynamicsignal.com>/v1/manage/targets/{id}
This endpoint allows you to update an existing target value/name.
Note: This endpoint is typically required when target values/names change often or are expected to change.
Delete targets:
DELETE https://<sample.dynamicsignal.com>/v1/manage/targets/{id}
You can use this endpoint to delete any target in the community.
Divisions
Using Divisions, managers can create custom content experiences for employees and target specific groups within a Division with personalized content. Managers can also assign manager permissions and responsibilities based on Division levels and role-specific manager access.
Get divisions:
GET https://<sample.dynamicsignal.com>/v1/divisions
This endpoint allows you to get a list of all divisions and division information from the community. It is important to maintain a master set of divisions IDs and attributes to reference when updating or assigning divisions to users.
Create divisions:
PUT https://<sample.dynamicsignal.com>/v1/division/create
You can use this endpoint to create a new division in the community. This endpoint allows you to add new divisions for custom content experiences for employees. Once a new division is created in the community, you will receive the ID of the target in the response.
Examples
Preregister user:
POST <sample.dynamicsignal.com>/v1/manage/preregister
{
"externalSsoUserId": "asharma", //username(identifier)
"email": "anuj@dynamicsignal.com",
"firstName": "Anuj",
"lastName": "Sharma",
"targetIds": [
6,
2,
4,
5
],
"sendInvitationEmail": "False",
"notificationsDefault": "AfterFirstLogin",
},
}
This will preregister a user with the email address anuj@dynamicsignal.com, first name Anuj, last name Sharma, and assign the user to location target IDs 8, 9, and 6. Since sendInvitationEmail is set to false, the user will not receive an email, and will not receive any notifications until the first login.
Batch Preregister:
POST <sample.dynamicsignal.com>/v1/batch/manage/preregister
{ "batchRequests":[{
"body":{
"externalSsoUserId":"asharma1", //username(identifier)
"email":"anuj@dynamicsignal.com"
"firstName":"Anuj",
"lastName":"Sharma",
"targetIds":"8,9,6"},
"method":"POST",
"sendInvitationEmail": "False",
"notificationsDefault": "AfterFirstLogin"},
{
"body":{
"externalSsoUserId":"dstest", //username(identifier)
"email":"dstest@dynamicsignal.com"
"firstName":"Dynamic",
"lastName":"Signal",
"targetIds":"8,9,6"},
"method":"POST",
"sendInvitationEmail": "False",
"notificationsDefault": "AfterFirstLogin"},
{
"body":{
"externalSsoUserId":"testaccount", //username(identifier)
"email":"testaccount@dynamicsignal.com"
"firstName":"Test",
"lastName":"Account",
"targetIds":"8,9,6"},
"method":"POST",
"sendInvitationEmail": "False",
"notificationsDefault": "AfterFirstLogin"}]}
Create New Target
POST https://<sample.dynamicsignal.com>/v1/manage/targets
{
"name": "California",
"definitionId": 1
}
This will create a new target California in target definition 1, which is Location.
Suspend User
POST https://<sample.dynamicsignal.com>/v1/manage/user/122/suspend
{
"id": 122
}
This will suspend the user account for Anuj, since the ID 122 is associated to that account. A unique user ID is generated for all the users on the platform when an account is created. This ID is a part of the response when a new user is created.
Unsuspend User
POST https://<sample.dynamicsignal.com>/v1/manage/user/122/unsuspend
{
"id": 122
}
This will unsuspend the user account for Anuj, since the ID 122 is associated to that account. A unique user ID is generated for all the users on the platform when an account is created. This ID is a part of the response when a new user is created.
Delete user details
DELETE https://<sample.dynamicsignal.com>/v1/manage/users
Add user details
PATCH https://<sample.dynamicsignal.com>/v1/manage/users
Replace user details
PUT https://<sample.dynamicsignal.com>/v1/manage/users
{
"userIds": [
122,
133
],
"targetIds": [
6,
2
]}
Depending on the method used, this will delete the properties from the two user accounts with ID 122, and 133. This will let you update user targets, tags, and attributes.
Please refer to the API Reference page for more examples.
The information contained in this document may include proprietary and/or business-confidential material and is intended only for Dynamic Signal customers and authorized users of Dynamic Signal’s products and services. Please be aware that any re-transmission, distribution or reproduction of this information beyond its intended recipient is strictly prohibited.