Welcome to WalkMe support

Please login in order to continue:

Work flows better with WalkMe
Work flows better with WalkMe.

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.


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

  1. Go to the Admin Center
  2. Navigate to the API Keys tab:
  3. Click Create new Key

From the Create new key panel:

  1. Name the key
    • Tip: Indicate the purpose of the key in the name to help you remember later
  2. Turn on Segments API
  3. Select Write and Read from the dropdown
  4. Click Create

From the Key Details panel:

  1. 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 tokenDeveloper 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:

  1. URL =
  2. Payload Type = application/x-www-form-urlencoded
  3. Data = grant_type → client_credentials

Add Basic Authentication 

  1. 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.

  1. Copy your Access Token

Now you can use the token to CreateGet, 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 '' \
--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",
    "scope""segments:write segments:read"

Make the call

Create segment

Description Create a new segment based on static list of users
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 '<GUID IS HERE>/test/walkme_<....>'

Payload / Body {"id": "<extneral id>",
"name": "<WalkMe Segment Name - will be visible in the Editor>",
"userIds": ["", ""] }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
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": [""]

Get segments

Description Get segments
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?

Thanks for your feedback!

Be part of something bigger.

Engage with peers, ask questions, share ideas

Ask the Community