Brief Overview

The Segments API lets external services create, update, retrieve, and delete WalkMe segments programmatically. Use it to automate content segmentation, apply advanced filtering in Insights, and streamline reporting.

For example, you can use Heap Analytics to create a segment and trigger a ShoutOut based on that segmentation logic.

Authentication Access Tokens

An access token is a credential used by an application to access an API. It informs the system that the bearer is authorized to perform specific actions, such as passing data from an external system to the WalkMe Menu.

Create access token

1. Open the WalkMe Console:
   
   • US Data Center
   • EU Data Center
   • SAP US Data Center
   • SAP EU Data Center
   • FedRAMP Data Center
   • Canada Data Center
2. Go to the Admin category
3. Select Access Management, then API Keys
4. Select Create New Key
5. Type a name for the key that indicates its purpose
6. Turn on Segments API
7. Select Write and Read from the dropdown
8. Select Create
9. In the Key Details panel, copy the Client ID and the Client Secret

Configuring the API Connection

To get your authorization token, refer to the Get Authorization Token reference on the Developer Hub.

Use the following details to configure your connection:

• URL: https://api.walkme.com/accounts/connect/token
• Method: POST
• Payload Type: application/x-www-form-urlencoded
• Data: grant_type client_credentials
• Basic authentication: Type the Client ID and Client Secret copied from the API Keys page

The system generates an access token after you submit the request. Copy the token and use it to manage segments.

cURL request example

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.

JSON response example

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

Endpoint Reference

Create segment

Create a new segment based on a static list of users.

• Method: POST
• URL: https://api.walkme.com/public/v1/user/system/{systemGuid}/segment
• Headers: Authorization: Bearer <Access Token>
• URL Parameters: systemGuid (found in the WalkMe Editor in the Snippet)
• Payload / Body: {"id": "<external id>", "name": "<WalkMe Segment Name>", "userIds": ["user1@company.com", "user2@company.com"]}
• Limitations:
  • Maximum 25,000 users per request
  • Maximum 100 characters per ID value

Update segment

Modify users within an existing segment.

• Method: PUT
• URL: https://api.walkme.com/public/v1/user/system/{systemGuid}/segment/{segmentGuid}
• Headers: Authorization: Bearer <Access Token>
• URL Parameters:
  • systemGuid: WalkMe system GUID
  • segmentGuid: The specific segment GUID (must include hyphens, for example: 12345aeb-123c-4d83-8b38-a5a456789d0a)
• Payload Parameters:
  • userIds: List of IDs to modify (limit 25,000)
  • action: Specify add, remove, or override
• Payload Example: {"action": "add", "userIds": ["jane.doe@walkme.com"]}

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

Get segments

Retrieve a list of existing segments.

• Method: GET
• URL: https://api.walkme.com/public/v1/user/system/{systemGuid}/segment
• Headers: Authorization: Bearer <Access Token>
• URL Parameters: systemGuid

Delete segments

Permanently remove a segment.

• Method: DELETE
• URL: https://api.walkme.com/public/v1/user/system/{systemGuid}/segment/{segmentId}
• Headers: Authorization: Bearer <Access Token>
• URL Parameters: segmentId (the ID of the target segment)

DELETE <a target="_blank" data-stringify-link="https://api.walkme.com/public/v1/user/system/{systemGuid}/segment/{segmentId}" delay="150" data-sk="tooltip_parent" href="https://api.walkme.com/public/v1/user/system/%7BsystemGuid%7D/segment/%7BsegmentId%7D" rel="noopener noreferrer">https://api.walkme.com/public/v1/user/system/{systemGuid}/segment/{segmentId}</a>

Technical Notes

• A new segment can take up to 10 minutes to appear in the Condition Builder
• WalkMe doesn't display users that were synced through this integration
• To use your segment in the WalkMe Editor, open the Condition Builder and select User Attributes, then External-Segment, then your segment name. Use only Is or Is not as the operator and type True in the input field