Candidate List Events

Candidate list events tell you when a list is created, changed or deleted, and when candidates are added to or removed from it. They fire for every change, whether it was made through the Candidates API or by someone using Popp.

If you keep lists in sync with your own system, use these events with the /v1/candidates/lists endpoints. Every event carries the list's externalId and says whether the change came from the API or from a user, so you can skip the echo of your own writes.

Available Events

Who made the change: source

Every candidate list event carries source:

source identifies the channel, not the caller. Every API key in your organization reports API, so if several of your systems call the API, compare the event with what you sent before you skip it.

Fields on every event

CANDIDATE_LIST_CREATED

Sent when a list is created. A list created in Popp has no externalId yet. To link it to your own record, set one with PATCH /v1/candidates/lists/{id}, using the recordId from this event.

Payload

{
  "event": "CANDIDATE_LIST_CREATED",
  "eventId": "evt_abc123",
  "eventTimestamp": "2026-10-06T10:00:00.000Z",
  "data": {
    "recordId": "list_abc123",
    "organizationId": "org_123456",
    "id": "list_abc123",
    "externalId": null,
    "title": "Senior engineers",
    "description": null,
    "userId": "user_789",
    "owner": "[email protected]",
    "source": "USER",
    "candidateProfilesCount": 0,
    "createdAt": "2026-10-06T10:00:00.000Z",
    "updatedAt": "2026-10-06T10:00:00.000Z"
  }
}

candidateProfilesCount is the number of candidates on the list. It is also sent on CANDIDATE_LIST_UPDATED and CANDIDATE_LIST_DELETED.

CANDIDATE_LIST_UPDATED

Sent when a list's title, description, owner or externalId changes. The payload carries the list as it is after the change, with the same fields as CANDIDATE_LIST_CREATED.

Adding or removing candidates does not send this event. Those changes send CANDIDATE_LIST_MEMBERSHIP_UPDATED.

When you set or change a list's externalId through the API, this event carries the new value with source: "API".

CANDIDATE_LIST_DELETED

Sent when a list is deleted. The payload carries the list as it was before deletion, with the same fields as CANDIDATE_LIST_CREATED, so you can match it to your own record by externalId.

CANDIDATE_LIST_MEMBERSHIP_UPDATED

Sent when candidates are added to or removed from a list. One request sends one event, listing the candidates it changed.

Payload

{
  "event": "CANDIDATE_LIST_MEMBERSHIP_UPDATED",
  "eventId": "evt_def456",
  "eventTimestamp": "2026-10-06T10:05:00.000Z",
  "data": {
    "recordId": "list_abc123",
    "organizationId": "org_123456",
    "id": "list_abc123",
    "externalId": "your_list_id",
    "title": "Senior engineers",
    "description": null,
    "userId": "user_789",
    "owner": "[email protected]",
    "source": "API",
    "createdAt": "2026-10-06T10:00:00.000Z",
    "updatedAt": "2026-10-06T10:00:00.000Z",
    "candidatesAdded": ["candidate_1", "candidate_2"],
    "candidatesRemoved": []
  }
}

Additional Fields

Only candidates that actually changed are listed. A candidate already on the list is not reported as added, and one that was not on it is not reported as removed.

This event does not carry candidateProfilesCount. Membership changes can happen at the same time, so a count here could already be out of date. Use candidatesAdded and candidatesRemoved, or read the list with GET /v1/candidates/lists/{id}.