Segments API (Beta)

Last Updated January 2, 2024

Brief Overview

Allow external services to create, edit, delete or use existing WalkMe segments data for the purpose of content segmentation, filtering on Insights, and reporting.

For example: Use Heap Analytics to create a new segment and show a ShoutOut according to the segmentation logic.

Note

WalkMe currently does not display users that were synced as part of this integration.

Authentication and creating an access token

What is an access token?

An access token is a credential that can be used by an application to access an API. They inform the API that the bearer of the token has been authorized to access a particular action.

The access token authenticates the API call, giving the application permission to pass data from its system to Workstation.

Create access token

Go to the Admin Center
Navigate to the API Keys tab: https://admin.walkme.com/account-api-keys
Click Create new Key

From the Create new key panel:

Name the key
- Tip: Indicate the purpose of the key in the name to help you remember later
Turn on Segments API
Select Write and Read from the dropdown
Click Create

From the Key Details panel:

Copy the Client ID and the Client Secret

Save the Client Secret

You will not see the Secret again so save it somewhere accessible, you'll need it again soon.

Authentication Token

For extra support and to get the authorization token: Developer page

Add information to the API connection application

For extra support Developer page.

Now it's time to fill in some information on your API connection application.

The information used below is universally necessary on all applications:

URL = https://api.walkme.com/accounts/connect/token
Payload Type = application/x-www-form-urlencoded
Data = grant_type → client_credentials

Add Basic Authentication

Client ID | Client Secret (copied from Admin Center)
- Example
  0o234234234UqD5d7 | JVnD346346346436345asfgasgbPt_4T7h2_

Once you've added this information, you will be given an access token.

Copy your Access Token

Now you can use the token to Create, Get, Update or Delete WalkMe segments, using the API documentation below.

You can also use the following cURL code blocks:

Request Example - cURL

curl --location --request POST 'https://api.walkme.com/accounts/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <credentials>' \
--data-urlencode 'grant_type=client_credentials'
# <credentials> is the base64 encoding of the consumer key and consumer secrect of the WalkMe account joined by a colon.

Response example - JSON

{    "access_token": "asdjkldfsjsdfhjksfdhjkxvc32cvhjhjksefbnxjnweuirou8sdfg8xdfjwkjr.sv8o8vuisuhvseuksfe",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": "segments:write segments:read"
}

Make the call

Create segment

Description	Create a new segment based on static list of users
URL	https://api.walkme.com/public/v1/user/system/{systemGuid}/segment
Method	POST
Headers	Authorization - Bearer - jwt
URL Parameters	`systemGuid` - WalkMe system GUID. You can get the system GUID from the Editor > Editor Menu > Snippet Copy the key that is in between 'https:cdn.walkme.com/users/<GUID IS HERE>/test/walkme_<....>'
Payload / Body	{"id": "<extneral id>", "name": "<WalkMe Segment Name - will be visible in the Editor>", "userIds": ["John@company.com", "Melissa@company.com"] }id: heap segment id> - optional param userIds: List of user ids - Limitations: Up to 25k users per request Up to 100 characters per ID value.

Update segment

Description Update an existing segment

URL https://api.walkme.com/public/v1/user/system/{systemGuid}/segment/{segmentGuid}

Method PUT

Headers uthorization - Bearer - jwt

systemGUID systemGuid- WalkMe system GUID
segmentGuid - WalkMe segment GUID**SegmentGuid will need to be placed in URL in its outputted format with a hyphen like: 12345aeb-123c-4d83-8b38-a5a456789d0a

Payload

application/json

{  "action": <enum("add"|"remove"|"override")>,
  "userIds": [<string>]
}

payload params:

userIds: List of users ids - limit - 25k users

action: selected update mode, accept only "add","remove" or "override"

payload example:

{"action": "add",
  "userIds": ["jane.doe@walkme.com"]
}

Get segments

Description	Get segments
URL	https://api.walkme.com/public/v1/user/system/{systemGuid}/segment
Headers	Authorization - Bearer - jwt
URL parameters	system Guid - WalkMe system GUID

Once a segment is created, the Editor will take up to 10 minutes to update with the new external segment in the condition builder.

To segment content based on if the user Id is in a specific Segment created by the API, go to the condition builder and select: User Attributes → External-Segment → Segment name → Is or Is not → "true"

You must only use Is or Is not as the operator, and "true" in the input field (other options will not work).

Was this article helpful?

Yes No

Yes

Thanks for your feedback!