Get Lead Events

Returns the latest events belonging to a given Lead ID.

Example

To fetch the events belonging to a lead with the ID "jPlz8TM628rzyCRPqrtcvm", send an authenticated GET request to the following URL:

https://api.yelp.com/v3/leads/jPlz8TM628rzyCRPqrtcvm/events

For the above request, a successful GET call would return the lead events if they exist in our system.
A sample response is shown in the example response box on the right under "200 - Events"

Order and Pagination

The order of events will be shown as it appears on Yelp, where the last message in the list represents the latest message in the conversation. Although the order will mostly follow the time_created field, it may deviate for certain events.

You can control the number of events returned using the limit parameter, and paginate through events using the older_than_cursor and newer_than_cursor parameters.

• limit: Defines the maximum number of events to return in a single response. The default is 20.

• older_than_cursor: Fetches events that occurred before the event identified by the given cursor value.

• newer_than_cursor: Fetches events that occurred after the event identified by the given cursor value.

Example

Using simplified API responses.

Assuming the following Message view on Yelp:

> Consumer Message 1

      Biz Response 1 <

>Consumer Message 2

      Biz Response 2 <

>Consumer Message 3

API Responses

No limit parameter

Notice how the latest event is the last entry in the array of events.

[
    { "event_content": {"text": "Consumer Message 1", ...}, "cursor": "cursor1", ...},
    { "event_content": { "text": "Biz Response 1", ... }, "cursor": "cursor2", ... },
    { "event_content": { "text": "Consumer Message 2", ... }, "cursor": "cursor3", ... },
    { "event_content": { "text": "Biz Response 2", ... }, "cursor": "cursor4", ... },
    { "event_content": { "text": "Consumer Message 3", ... }, "cursor": "cursor5", ... }
]

limit=1

Only the latest event shown on Yelp is returned.

[
    { "event_content": { "text": "Consumer Message 3", ... }, "cursor": "cursor5", ... }
]

limit=2

Only the latest 2 events shown on Yelp are returned.

[
    { "event_content": { "text": "Biz Response 2", ... }, "cursor": "cursor4", ... },
    { "event_content": { "text": "Consumer Message 3", ... }, "cursor": "cursor5", ... }
]

Using newer_than_cursor

Request:

GET /v3/leads/{ID}/events?limit=2&newer_than_cursor=cursor1

Response:

[
    { "event_content": { "text": "Biz Response 1", ... }, "cursor": "cursor2", ... },
    { "event_content": { "text": "Consumer Message 2", ... }, "cursor": "cursor3", ... },
]

Using older_than_cursor

Request:

GET /v3/leads/{ID}/events?limit=2&older_than_cursor=cursor5

Response:

[
    { "event_content": { "text": "Consumer Message 2", ... }, "cursor": "cursor3", ... },
    { "event_content": { "text": "Biz Response 2", ... }, "cursor": "cursor4", ... },
]

Request with No Events Before Cursor:

GET /v3/leads/{ID}/events?limit=2&older_than_cursor=cursor1

Response:

[]

How to Obtain Cursor Values

1. Initial API Call: Make a request without cursor parameters to retrieve the most recent events.
2. Extract Cursors: From the response, extract the cursor values from the events you're interested in.
3. Subsequent Calls: Use these cursor values with older_than_cursor or newer_than_cursor in your next request to fetch adjacent events.