Lifecycle History Object

Use lifecycle history resources to learn how a prospect is moving through their sales journey, from visitor to won opportunity. Learn what stage they’re currently in, how long they’ve been in that stage, and where that stage sits in the overall sales journey. For information about lifecycle stages, see Lifecycle Stage Resources. Learn more about prospect lifecycles in Salesforce Help.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

Note

The API to access the Lifecycle History object collection follows the conventions described in Version 5 Overview.

Supported Operations

Operation	Verb	URL Format	Ability Requirements
Read	`GET`	`https://pi.pardot.com/api/v5/objects/lifecycle-histories/<id>?<params>`	Prospect > Lifecycle > View report ability
Query	`GET`	`https://pi.pardot.com/api/v5/objects/lifecycle-histories?<params>`	Prospect > Lifecycle > View report ability

Fields

Read-Only Fields

Field	Type	Description
`id`	Integer	Account Engagement ID of this lifecycle history.
`prospectId`	Integer	Account Engagement ID for the prospect in this stage.
`previousStageId`	Integer	Account Engagement ID of the stage this prospect previously was in.
`nextStageId`	Integer	Account Engagement ID of the stage this prospect is in next.
`secondsElapsed`	Integer	Number of seconds for prospect to get to current stage.
`createdAt`	DateTime	Time lifecycle history is created in Account Engagement; Time is reported in API user's preferred timezone.
`prospect`	Prospect	Prospect object representing the prospect for this object. See documentation for Prospect for fields.
`previousStage`	Lifecycle Stage	Lifecycle stage object representing the previous stage this prospect previously was in. See documentation for Lifecycle Stage for fields.
`nextStage`	Lifecycle Stage	Lifecycle stage object representing the previous stage this prospect is in next. See documentation for Lifecycle Stage for fields.

Lifecycle History Read

Retrieve a single lifecycle history object following the conventions described in the Version 5 Overview.

Example request:

GET /api/v5/objects/lifecycle-histories/1?id,prospectId,previousStageId,nextStageId,secondsElapsed,createdAt
Host: pi.pardot.com
Authorization: Bearer <access-token>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": 1,
    "createdAt": "2022-07-05T07:03:03-04:00",
    "nextStageId": 1,
    "previousStageId": null,
    "prospectId": 1,
    "secondsElapsed": null
}

Lifecycle History Query

Retrieving a collection of lifecycle histories follows the conventions described in Version 5 Overview.

Sortable Fields

When executing a query, the following fields can be specified in the orderBy parameter. See the conventions for query described in the Version 5 Overview.

id
createdAt

Example request:

GET /api/v5/objects/lifecycle-histories?fields=id,prospectId,previousStageId,nextStageId,secondsElapsed,createdAt&orderBy=id
Host: pi.pardot.com
Authorization: Bearer <access-token>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "nextPageToken": null,
    "nextPageUrl": null,
    "values": [
        {
            "id": 1,
            "createdAt": "2022-07-05T07:03:03-04:00",
            "nextStageId": 1,
            "previousStageId": null,
            "prospectId": 1,
            "secondsElapsed": null
        },
        {
            "id": 2,
            "createdAt": "2022-07-09T01:36:33-04:00",
            "nextStageId": 2,
            "previousStageId": 1,
            "prospectId": 1,
            "secondsElapsed": 326010
        }
    ]
}

Filtering Results

When executing a query, the following parameters can be used to filter the returned results. These parameters can be specified in the request along with any shared parameters defined in Version 5 Overview. When specifying more than one parameter, all parameters must match the record in order for it to be returned in the results.

Parameter	Description
`id`	Returns any lifecycle history where ID is equal to the given integer value.
`idList`	Returns any lifecycle history where ID is included in the given list of values.
`idGreaterThan`	Returns any lifecycle histories where ID is greater than the specified value, non-inclusive.
`idGreaterThanOrEqualTo`	Returns any lifecycle histories where ID is greater than or equal to the specified value.
`idLessThan`	Returns any lifecycle histories where ID is less than the specified value, non-inclusive.
`idLessThanOrEqualTo`	Returns any lifecycle histories where ID is less than or equal to the specified value.
`createdAt`	Returns any lifecycle histories where CreatedAt is equal to the given datetime value.
`createdAtAfter`	Returns any lifecycle histories where CreatedAt is after the given datetime value, non-inclusive.
`createdAtAfterOrEqualTo`	Returns any lifecycle histories where CreatedAt is after or equal to the given datetime value.
`createdAtBefore`	Returns any lifecycle histories where CreatedAt is before the given datetime value, non-inclusive.
`createdAtBeforeOrEqualTo`	Returns any lifecycle histories where CreatedAt is before or equal to the given datetime value.

Example request:

GET /api/v5/objects/lifecycle-histories?fields=id,prospectId,previousStageId,nextStageId,secondsElapsed,createdAt&idGreaterThan=3&idLessThan=5
Host: pi.pardot.com
Authorization: Bearer <access-token>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "nextPageToken": null,
    "nextPageUrl": null,
    "values": [
        {
            "id": 4,
            "createdAt": "2022-07-04T00:37:28-04:00",
            "nextStageId": 1,
            "previousStageId": null,
            "prospectId": 2,
            "secondsElapsed": null
        }
    ]
}

Lifecycle History Object

Supported Operations

Fields

Read-Only Fields

Lifecycle History Read

Lifecycle History Query

Sortable Fields

Filtering Results

No Results