Participant Event Subscriptions

There are two methods that are supported for notifying your application of these status change events: (1) HTTP POST, and (2) HTTP GET.

If using HTTP POST, data elements are sent via a standard HTTP(S) POST of urlencoded name value pairs as an “application/x-www-form-urlencoded” mime type. This is the same format used by standard HTTP form post actions, so most server side processors understand how to parse form posts.

If you only want to be notified only on the first time the participant event occurs, set AlwaysRequired=false (this is the default). If you want to be notified for every time the participant event occurs, set AlwaysRequired=true.

For information about controlling event behavior, timeout settings, and retry configuration, see Webhook Configuration.

Common Data Elements

Below are common data elements that will be included in all Participants Event Subscriptions.

Name	Value
SecurityToken	Please reference Security Token usage details.
TransID	The TransID is a standard 10 digit ID used for a transaction as discussed elsewhere. Example: `1234567890`
PartID	The PartID is a standard 10 digit ID used for a participant as discussed elsewhere. Example: `1234567890`
PartStatus	The PartStatus will be one of the following one-digit integer values: `2` Pending `4` Complete `6` Email sent - Participant has been notified by email but is still in the Pending status. You will receive a notification every time an email notice is sent to the participant. So if there are three email notices sent, then you will receive three status update messages related to it. This value is only valid for PartStatus and SigStatus. `7` Closed `8` Cancelled `9` Expired
TXStatus	The TXStatus will be one of the following one-digit integer values: `2` Pending `4` Complete `7` Closed `8` Cancelled `9` Expired `10` Voided
PartAccessToken	DEPRECATED
ps_securitytoken	guid

Status Change

You can subscribe to Participant status change events by adding a Workflow Action to the Participant.

The data elements sent in the GET or POST are all the common data elements plus the following:

Name	Value
EventType	`participant`

If the Participant's CancelledTaskBehaviorType is set to AutomaticCancel or DisplayCancelOrSuspendOption and they cancel a transaction, the notification will be sent and the returned TXStatus and PartStatus values for the transaction will be 8. If the Participant's CancelledTaskBehavior is set to AutomaticSuspend, no notification will be sent because the status stays as a 2 which is the pending status. Likewise, if the Participant's CancelledTaskBehavior is set to DisplayCancelOrSuspend and they choose to only suspend their process after hitting the initial cancel button, no notification will be sent because the status stays in a 2 pending status.

participant = new ParticipantInsertModel()
              {
                  FullName = "John Smith",
                  EmailAddress = "testing@alphatrust.com",
                  SendRequestViaEmail = true,
                  WorkflowActions = new List<object>
                                    {
                                        new ParticipantWorkflowActionModel()
                                        {
                                            Type = ParticipantWorkflowActionModel.TypeEnum.SubscribeToStatusChangeNotificationsByPost, //or ...ByGet
                                            Data = "required-response-text=RECEIVED", // Note: timeout and retry parameters are now server-configured
                                            Url = "https://myapp.mydomain.com/statuslistener.php"
                                        }
                                    }
              }

A completed participant from that uses the above code would see something like the following as the posted status notification values:

{
    "TransID": "1234567890",
    "PartID": "1234567890",
    "TXStatus": 2,
    "PartStatus": 4,
    "EventType": "participant",
    "ps_securitytoken": "4bf44fb0-f695-40b5-821d-c22273e11c30"
}

Likewise, if the participant was using a SubscribeToStatusChangeNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890PartID=1234567890&TXStatus=2&PartStatus=4&EventType=participant&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Session Start

You can subscribe to Participant session start change events by adding a Workflow Action to the Participant.

The data elements sent in the GET or POST are all the common data elements plus the following:

Name	Value
EventType	`participant-session-begin`

participant = new ParticipantInsertModel()
              {
                  FullName = "John Smith",
                  EmailAddress = "testing@alphatrust.com",
                  SendRequestViaEmail = true,
                  WorkflowActions = new List<object>
                                    {
                                        new ParticipantWorkflowActionModel()
                                        {
                                            Type = ParticipantWorkflowActionModel.TypeEnum.SubscribeToSessionStartNotificationsByPost, //or ...ByGet
                                            Data = "required-response-text=RECEIVED", // Note: timeout and retry parameters are now server-configured
                                            Url = "https://myapp.mydomain.com/statuslistener.php",
                                            NotRequiredAfterFirstOccurrence = true
                                        }
                                    }
              }

A completed participant from that uses the above code would see something like the following as the posted status notification values:

{
    "TransID": "1234567890",
    "PartID": "1234567890",
    "TXStatus": 2,
    "PartStatus": 4,
    "EventType": "session-begin",
    "ps_securitytoken": "4bf44fb0-f695-40b5-821d-c22273e11c30"
}

Likewise, if the participant was using a SubscribeToSessionStartNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890PartID=1234567890&TXStatus=2&PartStatus=4&EventType=session-begin&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Authentication Failure

You can subscribe to Participant authentication failure events by adding a Workflow Action to the Participant.

The data elements sent in the GET or POST are all the common data elements plus the following:

Name	Value
EventType	`participant-auth-failure-notify`

participant = new ParticipantInsertModel()
            {
                FullName = "John Smith",
                EmailAddress = "testing@alphatrust.com",
                SendRequestViaEmail = true,
                WorkflowActions = new List<object>
                {
                    new ParticipantWorkflowActionModel()
                    {
                        Type = ParticipantWorkflowActionModel.TypeEnum.SubscribeToAuthenticationFailureNotificationsByPost, // or ...ByGet
                        Data = "required-response-text=RECEIVED", // Note: timeout and retry parameters are now server-configured
                        Url = "https://myapp.mydomain.com/statuslistener.php"
                    }
                }
            }

A completed participant from that uses the above code would see something like the following as the posted status notification values:

{
    "TransID": "1234567890",
    "PartID": "1234567890",
    "TXStatus": 2,
    "PartStatus": 4,
    "EventType": "participant-auth-failure-notify",
    "ps_securitytoken": "4bf44fb0-f695-40b5-821d-c22273e11c30"
}

Likewise, if the participant was using a SubscribeToAuthenticationFailureNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890PartID=1234567890&TXStatus=2&PartStatus=4&EventType=participant-auth-failure-notify&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Participant Reassigned

You can subscribe to Participant reassigned events by adding a Workflow Action to the Participant.

The data elements sent in the GET or POST are all the common data elements plus the following:

Name	Value
ReassignedPartID	The ReassignedPartID is a standard 10 digit ID used for a participant that all the tasks will be reassigned to and will be a NEW participant that was created during the reassigning workflow action. Example: `1234567890`
EventType	`participant-reassigned`

participant = new ParticipantInsertModel()
              {
                  FullName = "John Smith",
                  EmailAddress = "testing@alphatrust.com",
                  SendRequestViaEmail = true,
                  WorkflowActions = new List<object>
                                    {
                                        new ParticipantWorkflowActionModel()
                                        {
                                            Type = ParticipantWorkflowActionModel.TypeEnum.SubscribeToReassignedNotificationsByPost, //or ...ByGet
                                            Data = "required-response-text=RECEIVED", // Note: timeout and retry parameters are now server-configured
                                            Url = "https://myapp.mydomain.com/statuslistener.php"
                                        }
                                    }
              }

A completed participant from that uses the above code would see something like the following as the posted status notification values:

{
    "TransID": 1234567890,
    "PartID": 1234567890,
    "TXStatus": 2,
    "PartStatus": 4,
    "EventType": "participant-reassigned",
    "ReassignedPartID": 1234567891,
    "ps_securitytoken": "4bf44fb0-f695-40b5-821d-c22273e11c30"
}

Likewise, if the participant was using a SubscribeToStatusChangeNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890PartID=1234567890&TXStatus=2&PartStatus=4&EventType=participant-reassigned&ReassignedPartID=1234567891&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Experian Precise ID Victim Statement

You can subscribe to Experian Precise ID Victim Statement events by adding a Workflow Action to the Participant.

The data elements sent in the GET or POST are all the common data elements plus the following:

Name	Value
VictimStatement	String of text returned by Experian for the victim statement.
EventType	`participant-reassigned`

participant = new ParticipantInsertModel()
              {
                  FullName = "John Smith",
                  EmailAddress = "testing@alphatrust.com",
                  SendRequestViaEmail = true,
                  WorkflowActions = new List<object>
                                    {
                                        new ParticipantWorkflowActionModel()
                                        {
                                            Type = ParticipantWorkflowActionModel.TypeEnum.SubscribeToPreciseIdVictimStatementNotificationsByPost, //or ...ByGet
                                            Data = "required-response-text=RECEIVED", // Note: timeout and retry parameters are now server-configured
                                            Url = "https://myapp.mydomain.com/statuslistener.php"
                                        }
                                    }
              }

A completed participant from that uses the above code would see something like the following as the posted status notification values:

{
    "TransID": "1234567890",
    "PartID": "1234567890",
    "TXStatus": 2,
    "PartStatus": 4,
    "EventType": "participant-victim-statement-notify",
    "ps_securitytoken": "4bf44fb0-f695-40b5-821d-c22273e11c30"
}

Likewise, if the participant was using a SubscribeToPreciseIdVictimStatementNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890PartID=1234567890&TXStatus=2&PartStatus=4&EventType=participant-victim-statement-notify&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30