Incydr API: Migrate watchlists from v1 to v2

Overview

This article provides guidance on migrating from the /v1/watchlists/ Incydr API endpoint to the /v2/watchlists/ endpoint. Depending on your specific API implementation, migrating may involve updating how to request information about users and actors, and how to process the response. 

Deprecation and end-of-life notice
The /v1/watchlists/ endpoint was deprecated on March 13, 2024, and will stop working on February 28, 2026. To avoid potential service interruptions, you must update scripts and integrations that use the /v1/watchlists/ endpoint to use the /v2/watchlists/ endpoint instead.

Key differences between v1 and v2

• The main difference between the /v1/watchlists/ and /v2/watchlists/ endpoints is that the v2 endpoint requires actorId instead of userId.
• Aside from the actorId and userId changes, all other /v1/watchlists fields have similar or exact equivalents in the /v2/watchlists API. In many cases, the only update to request and response formats is the change from v1 to v2.
• For complete schema details, see the Incydr Developer Portal.

Change area	Deprecated API: v1/watchlists	New API: v2/watchlists
User/Actor ID handling	Accepted both user ID and actor ID in userId fields	Only accepts actor ID
ID translation	Automatically translated user ID to actor ID	No automatic translation; requires a valid actor ID
Field naming	"User" terminology, such as userId field	"Actor" terminology, such as actorId field

Differences between actors and users

Within Incydr, the same person can have both a user ID and a separate actor ID. For some older Incydr user accounts, the user ID and actor ID may have the same value. For more recently-created accounts, the user ID and actor ID have different values.

The Actor and User APIs are optimized for different use cases:

• Users API (/users/*): For user-centric attributes such as email addresses and usernames.
• Actors API (/actors/*): For managing consolidated identities that generate events within Incydr. Multiple user accounts can be adopted into a single actor, creating a parent-child relationship.

Migration checklist

• Replace all /v1/watchlists endpoints with /v2/watchlists.
• Replace all users references with actors. For example:
  

  Deprecated v1 value	Replacement v2 value
  /v1/watchlists/{watchlist_id}/included-users/add	/v2/watchlists/{watchlist_id}/included-actors/add
  /v1/watchlists/{watchlist_id}/excluded-users/add	/v2/watchlists/{watchlist_id}/excluded-actors/add
  /v1/watchlists/{watchlist_id}/members/{user_id}	/v2/watchlists/{watchlist_id}/members/{actor_id}

• Convert userId values to actorId values:
  • Use the Actors API to send a GET request to /v1/actors/actor/name/{name}/parent
  • Replace {name} with a username or email address
  • Review the response for the actorId

Related topics

• Incydr API endpoint updated for Q4 2025
• Incydr API: Migrate from alerts to sessions
• Incydr Developer Portal: Watchlists
• Incydr Developer Portal: Actors
• Incydr Developer Portal: Users