To gain access to the Rival API, a developer must register an Application with Rival and obtain an Application Key. To register an Application and get your initial API key and Application Id, contact your Rival support representative.

APIs are provided for administrative tasks as well as operational tasks. Adminstrative tasks focus on provisioning new Organizations and managing Applications. Operational tasks focus on managing chats, reports, distributions, etc within a Research Domain.

Authentication to API endpoints is performed by providing your API key and Application Id in the respective x-api-key and x-application headers. Most requests, such as managing Projects or pulling data, are scoped to a single Reseach Domain. In order to perform these tasks, a connection must be established between the Research Domain and the Application that issued the request. Once this connection is established the application can set the x-research-domain header to the id of the targeted Research Domain. When an Application is used to create a Research Domain a connection is automatically established between the Application and the Research Domain.

If credentials are missing from the x-api-key, x-application, or x-research-domain headers, or if those credentials are not valid, a 401 Unauthorized response will be returned. If the application has not been authorized to perform an action for the targetted Research Domain, the API will return a 403 forbidden response and the request will be rejected.

Top-level API resources have support for fetching collections of resources. These collections can be paginated using a cursor-based pagination technique that relies on offset/limit pairs using the first, last, after, and before query string parameters. Additional filtering may be available on some collection APIs by specifying filters in the form of <field name>=<value> (eg. type=chat).

first - postitive integer

Limits the response to accept the first n resources in the collection, starting from the cursor position specified by 'after'. When 'after' is not specified, the first resources in the collection are returned. Default value: 20

last - postitive integer

Limits the response to accept the previous n resources in the collection, before the cursor specified by 'before'. When 'before' is not specified, the last resources in the collection are returned. Default value: 20

after - string

An opaque cursor that marks the pagination position of the last item in the previous response. Used in conjunction with 'first'.

before - string

An opaque cursor that marks the pagination position of the first item in the previous response. Used in conjunction with 'last'.

Examples

First 10 items of a collection

  GET /v1/research-domains?first=10

Next page of 10 items after provided cursor

  GET /v1/research-domains?first=10&after=ZmEzNzQzMzItOTAzNC00MzgzLWEyZTUtZTIyYTczMTFkOTAy

Previous page of 15 items before provided cursor

  GET /v1/research-domains?last=15&before=ZmEzNzQzMzItOTAzNC00MzgzLWEyZTUtZTIyYTczMTFkOTAy

Collection responses return pagination metadata in the pageInfo field and an array of resources in the data field.

startCursor - string

An opaque cursor that points to the first item in the response. Can be used as the before value on subsequent requests.

endCursor - string

An opaque cursor that points to the last item in the response. Can be used as the after value on subsequent requests.

hasNextPage - boolean

Returns true if more data exists after the position of endCursor

hasPreviousPage - boolean

Returns true if more data exists prior to the position of startCursor

Example Response

  {
    "pageInfo": {
      "startCursor": "NDk3ZjZlY2EtNjI3Ni00OTkzLWJmZWItNTNjYmJiYmE2ZjA4",
      "endCursor": "NDk3ZjZlY2EtNjI3Ni00OTkzLWJmZWItNTNjYmJiYmE2ZjA4",
      "hasNextPage": true,
      "hasPreviousPage": false
    },
    "data": [
      ...
    ]
  }

Endpoints and webhooks that return Participant data use a dynamically generated schema. The Participant data object is always represented as a Map<string, AttributeValue> where each item in the map represents an Attribute. The key field of the map is represented as a human-readable alphanumeric label no longer than 55 characters in length. The value of the map will be represented in a format that is dependent on the data type of the Attribute that is being represented. If no value is captured for a Participant for a particular Attribute the value will be null.

String

Strings represent textual data. Typically, a string value is captured from an Open-Ended Text Question.

Examples

{
  "Name": "John D. Rockefeller",
  "Biography": " An American business magnate and philanthropist. He is widely considered the wealthiest American of all time and the richest person in modern history."
}

Enumeration

Enumeration values represent a single member from a closed set of elements. Typically, an enumerated value is captured from a Single Choice Question. Values are represented as positive integers where each unique integer maps to exactly one member in the enumerated set.

Example

Given a Single Choice Question "Profession", with the allowable choices

• Government Employee - 1
• Private Employee - 2
• Self Employed - 3
• Student - 4
• Other - 5

A value of "Self Employed" would be represented as

{
    "Profession": 3
}

Enumeration Sets

Enumeration Set values represent an unordered subset of members from a closed set of elements. Typically, an enumerated set value is captured from a Multiple Choice Question. Values are represented as arrays of positive integers where each unique integer maps to exactly one member in the enumerated set.

Example

Given a Multiple Choice Question "Bank_Account_Types", with the allowable choices

• Chequeing - 1
• Savings - 2
• RRSP - 3
• TFSA - 4

A value containing "Savings" and "Chequeing" would be represented as

{
  "Bank_Account_Types": [1, 2]
}

Media

Media responses are currently not available in the Rival API.

Rival uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an internal error in the Rival platform.

Response body's are returned as JSON-encoded payloads. Each error response includes a standard set of properties

code string

The error code represents a classification for the error. Application logic may use error codes to set up specific handlers for different types of errors.

message string

A human-readable message providing more details about the error. Error messages are always returned in English and are intended for development use only. Application developers should provide more friendly and context aware error messages to display to end users.

errorId string

A unique identifier that can be provided back to Rival to facilitate support requests.

data object

Additional data may be provided for specific error codes. Not all errors are guaranteed to return additional data.

Unauthorized 401

No API key or bearer token was provided on the API request, or the provided credentials were not valid.

Forbidden 403

The request was not allowed

ConflictError 409

Resource to be created may already exist, where uniqueness is enforced.

Account Provisioning API endpoints manage provisioning of Organizations and Research Domains. Requests to Admin APIs require the calling Application to have an elevated permission level.

An Organization represents the account of a business entity that will directly interact with the Rival platform or indirectly benefit from the use of the Rival platform. Organizations are the top level resource that all other resources are created under.

A Research Domain is a market research point of control. A Research Domain organizes the market research artifacts and data that pertains to that Research Domain. Market research artifacts and data are segregated from other Research Domains.

Each Research domain is associated with an Organization that is the ownerOrganization and another Organization that is the managementOrganization. An Organization that manages a Research Domain is not always the Organization that owns the Research Domain. When a Research Domain is created via the create research domain API, an owner Organization is explicitly specified and the calling Application's Organization is implicitly set as the management Organization.

Participant Management API enpoints enable Participants in a Rearsearch Domain to be synchronized with an external system of record.

A Participant is an account of a person that provides insights into a Research Domain by engaging in a dialogue with an agent through a chat.

Rival supports webhooks to notify your application when an event happens. Rival generates JSON-encoded POST requests over HTTPS to send notifications to your application. These notifications can be used to execute actions in your backend system.

You can use webhook event notifications to alert your application when:

• A participant has subscribed to the Rival platform, so that a record can be inserted into your customer relationship management database.

• A value has been captured for a specific attribute of a participant, so that information can be synchronized in your customer relationship management database.

• A paticipant has completed a chat.

The following steps can be taken to start receiving webhook notifcations in your application:

1. Identify the events you want to monitor.

2. Build a publicly accessible HTTPS endpoint.

3. Register the publicly accessible HTTPS url in the Rival platform via the create event subscription endpoint.

Your endpoint must be configured to read event payloads for the type of event notification that the endpoint is subscribed to. Rival sends notifications you your endpoint as a POST request with a JSON payload.

Each event is structured as an object with a type, id, occuredAt, and a data field. See get event for a detailed view of the event payload.

{
  "type": "ParticipantSubscribed",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": { ... }
}

Your endpoint must quickly return a successful status code (2xx) prior to any complex or time consuming operations that may cause a timeout. In scenarios where operations may take longer than a few hundred milliseconds, it is a recommended practice to write the event to a queue and return a success response immediately after the write is complete.

In the event that your endpoint returns an http code in the 3xx, 4xx, or 5xx category, or if a requests times out, Rival will automatically attempt to retry sending the event payload.

Rival signs all webhook events it sends to your endpoints by including a cryptographic signature in the x-signature request header. This allows applications to verify that requests were sent from Rival, not by a third party. In order to verify the signature you need to have access to the API Key that was provided when your application was registered with the Rival platform (or subsequently generated during key rotation).

The x-signature header contains a timestamp and a signature for each active API key for your application. Typically an application will only have a single active API key unless key rotation is currently in progress and a grace period has been provided for decomissioning the previous key. The signature will take the following form:

t=1638904318,

s=f94debcb07dfc2fc6d4a4ac0ef489f604c8a6ee8f12470e6e31f482a47d0d015,

s=db5e6477ce19b5ebaa2cefd534b4e0fc507809396b73347a1d171e1082fd2095

Rival generates signatures using a hash-based message authentication code (HMAC) with SHA-256. The following steps can be used to verify the signature

1. Split the header on the , character. Next, split the resultant string array on the = character to generate an array of key-value pairs.

2. Obtain the timestamp by finding the key-value pair where the key is t. The timestamp is recorded in Unix time with no milliseconds. In order to defend against replay attacks it is recommended to verify that the timestamp falls within some reasonable tolerance from the current time (eg. within the last 5 minutes). When the Rival platform generates retry requests a new timestamp and signature is created for each delivery attempt.

3. Generate the signed payload. This payload is formed by concatenating the string value of the timestamp from step 2; the . character; and the JSON payload (ie. the request body). Ensure that the raw payload is used in this step. Many web server frameworks will try to parse and format the JSON payload which may lead to re-ordering of fields or inserting additional whitespace.

4. Compute the HMAC authentication code. Using SHA-256 hash function and your API key as the HMAC key, compute the expected signature for the payload generated in step 3.

5. Compare the expected signature computed in step 4 with the provided signature(s) from step 1's key-value pair array where the key is s. There should be an exact string match for one of the provided signatures. It is recommended to use a constant-time string comparison algorithm when comparing the provided and expected signatures to protect against timing attacks.

const {createHmac, timingSafeEqual} = require('crypto')

const express = require('express')


const verifySignature = (sigHeader, body, key) => {
  if (!sigHeader || !body) {
    return false
  }

  let signatures = []

  try {
    const pairs = sigHeader.split(',')
    let timestamp = 0

    for (let pair of pairs) {
      const [key, value] = pair.split('=')
      if (key === 't') {
        timestamp = Number.parseInt(value)
      } else  if (key === 's') {
        signatures.push(value)
      } else {
        return false
      }
    }

    // Ensure that a signature exists.
    if (signatures.length < 1) {
      return false
    }
    if (timestamp === 0) {
      return false
    }

    // Limit the number of signatures that will be verified.
    if (signatures.length > 5) {
      return false
    }

    // Prevent replay attacks https://en.wikipedia.org/wiki/Replay_attack
    const maximumTimeDeltaInSeconds = process.env.MAX_SIGNATURE_AGE_IN_SECONDS ? Number(process.env.MAX_SIGNATURE_AGE_IN_SECONDS) : 60
    const currentTime = Math.floor(Date.now() / 1000)
    if (Math.abs(currentTime - timestamp) > maximumTimeDeltaInSeconds) {
      return false
    }

    // Compute the exptected signature.
    const stringToBeSigned = `${timestamp}.${body}`
    const hmac = createHmac('sha256', key)
    const expectedSignature = hmac.update(stringToBeSigned).digest('hex')

    for (let signature of signatures) {
      // Prevent timing attacks https://en.wikipedia.org/wiki/Timing_attack
      if (timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
        return true
      }
    }
    return false
  } catch (ex) {
    console.log(ex)
    return false
  }
}


const app = express()

// Configure express to include the raw request body prior to JSON parsing on the request object.

app.use(express.json({
  limit: '5mb',
  verify: (req, res, buf) => {
    req.rawBody = buf.toString()
  },
}))


app.post('/rival-webhooks', (req, res) => {
  if (!verifySignature(
    req.headers['x-signature'],
    req.rawBody, // The original 'raw' request body payload before json parsing/formatting.
    process.env.API_KEY
  )) {
    // Send a non 2xx http status code if signature verification fails.
    res.sendStatus(401)
    return
  }

  // TODO: Perform action.

  // Return a 2xx status code after successful processing.
  res.sendStatus(200)
})

The Rival platform allows application to subscribe for notifications on various event types. As the platform evolves new event types may be added to this list. Any application code that is reading an event list should be able to handle the presence of additional event types.

Occurs when the participation status of a Chat Engagement transitions to Completed.

Criteria fields

chat string An id of a Chat in the current Reseach Domain. Webhook reqeusts will be sent for participation completions for this Chat. In order to subscribe to participation completions for multiple Chats, an event subscription must be set up for each Chat.

Payload fields

participant object A descriptor of the Participant that completed the Chat.

• id string A unique identifier for the Participant

• registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

chat object A descriptor of the Chat that was completed.

• id string A unique identifier for the Chat

• name string The name of the Chat as it appeared at time of completion.

engagement object A descriptor of the Engagement

• id string A unique identifier for the Engagement

• durationInSeconds number The duration of the Engagement.

• startedAt datetime The UTC date and time when the Engagement began.

• endedAt datetime The UTC date and time when the participation status of the Engagement transitioned to Completed.

• status string The participation status of the Engagement at the time of completion. This value will always be "Completed" for the Chat Participation Completed event.

values Map<string, object> The response data that was collected in the Chat Engagement. See Participant data objects for details about the payload structure.

Example

{
  "type": "ChatParticipationCompleted",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
    "participant": {
        "id": "151bd259-18b7-48f6-a655-713bf0192bec",
        "registeredIdentifiers": {
            "StarFinancial": "A1103451252",
            "Rival": "MDfp8Q0i"
        }
    },
    "chat": {
        "id": "9ef59d1c-5c7f-4c73-a1e1-3fedce9173e2",
        "name": "Profiling Questionnaire (Jan. 2022)"
    },
    "engagement": {
        "id": "7a7d6b80-149e-4675-92a9-c00a9433b644",
        "durationInSeconds": 372,
        "startedAt": "2022-03-09T11:30:00.323Z",
        "endedAt": "2022-03-09T11:36:12.323Z",
        "status": "Completed"
    },
    "values": {
        "Name": "John D. Rockefeller",
        "Biography": " An American business magnate and philanthropist. He is widely considered the wealthiest American of all time and the richest person in modern history.",
        "Profession": 3,
        "Bank_Account_Types": [1, 2],
        "Twitter_Account": null
    }
  }
}

Occurs when the participation status of a Chat Engagement transitions to Disqualified.

Criteria fields

chat string An id of a Chat in the current Reseach Domain. Webhook reqeusts will be sent for participation disqualifications for this Chat. In order to subscribe to participation disqualifications for multiple Chats, an event subscription must be set up for each Chat.

Payload fields

participant object A descriptor of the Participant that got disqualified during the Chat.

• id string A unique identifier for the Participant

• registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

chat object A descriptor of the Chat in which the participant got disqualified.

• id string A unique identifier for the Chat

• name string The name of the Chat as it appeared at time of disqualification.

engagement object A descriptor of the Engagement

• id string A unique identifier for the Engagement

• durationInSeconds number The duration of the Engagement.

• startedAt datetime The UTC date and time when the Engagement began.

• endedAt datetime The UTC date and time when the participation status of the Engagement transitioned to Disqualified.

• status string The participation status of the Engagement at the time of disqualification. This value will always be "Disqualified" for the Chat Participation Disqualified event.

values Map<string, object> The response data that was collected in the Chat Engagement. See Participant data objects for details about the payload structure.

Example

{
  "type": "ChatParticipationDisqualified",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
    "participant": {
        "id": "151bd259-18b7-48f6-a655-713bf0192bec",
        "registeredIdentifiers": {
            "StarFinancial": "A1103451252",
            "Rival": "MDfp8Q0i"
        }
    },
    "chat": {
        "id": "9ef59d1c-5c7f-4c73-a1e1-3fedce9173e2",
        "name": "Profiling Questionnaire (Jan. 2022)"
    },
    "engagement": {
        "id": "7a7d6b80-149e-4675-92a9-c00a9433b644",
        "durationInSeconds": 372,
        "startedAt": "2022-03-09T11:30:00.323Z",
        "endedAt": "2022-03-09T11:36:12.323Z",
        "status": "Disqualified"
    },
    "values": {
        "Name": "John D. Rockefeller",
        "Biography": " An American business magnate and philanthropist. He is widely considered the wealthiest American of all time and the richest person in modern history.",
        "Profession": 3,
        "Bank_Account_Types": [1, 2],
        "Twitter_Account": null
    }
  }
}

Occurs when a participant responds to a Question as part of a Chat Engagement.

Criteria fields

chat string An id of a Chat in the current Reseach Domain. Webhook reqeusts will be sent for questions responded for this Chat.

question string An id of a specific question for the chat whose id is being provided in the criteria above. Webhook requests will be sent whenver the participant responds to this question. In order to subscribe to response provided for multiple questions, an event subscription must be set up for each question under each chat.

Payload fields

participant object A descriptor of the Participant that responded to the Question.

• id string A unique identifier for the Participant

• registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

chat object A descriptor of the Chat as part of which Question is being responded.

• id string A unique identifier for the Chat

• name string The name of the Chat as it appeared at time of responding to the Question.

engagement object A descriptor of the Engagement

• id string A unique identifier for the Engagement

question object A descriptor of the Question that is being responded

• id string A unique identifier for the Question

• label string A label that is defined for the Question

• type string Type of the Question

value: string/number/array Response value/s as associated number/s or a string depending on the Question Type. See Participant data objects for details about the value based on the Question Type.

Example

{
  "type": "ChatResponseProvided",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
      "participant": {
          "id": "151bd259-18b7-48f6-a655-713bf0192bec",
          "registeredIdentifiers": {
              "StarFinancial": "A1103451252",
              "Rival": "MDfp8Q0i"
          }
      },
      "chat": {
          "id": "9ef59d1c-5c7f-4c73-a1e1-3fedce9173e2",
          "name": "Profiling Questionnaire (Jan. 2022)"
      },
      "engagement": {
          "id": "7a7d6b80-149e-4675-92a9-c00a9433b644",
      },
      "question": {
          "id": "f89e8b41-b834-4a6c-95b9-176186f047c3",
          "label": "Profession",
          "type": "SingleChoice"
      },
      "value": 3
  }
}

Occurs when the chat reaches a terminal state. This may be due to a Participant completing interaction with the final card in the Chat, or it may be due to a card type that terminates the chat (e.g. jump ahead card or redirect card).

Criteria fields

chat string An id of a Chat in the current Reseach Domain. Webhook reqeusts will be sent for participation completions for this Chat. In order to subscribe to chat script ended event for multiple Chats, an event subscription must be set up for each Chat.

Payload fields

participant object A descriptor of the Participant that completed interaction with final card in the Chat.

• id string A unique identifier for the Participant.

• registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

chat object A descriptor of the Chat that was ended.

• id string A unique identifier for the Chat.

• name string The name of the Chat as it appeared at time of script end.

engagement object A descriptor of the Engagement.

• id string A unique identifier for the Engagement.

• durationInSeconds number The duration of the Engagement.

• startedAt datetime The UTC date and time when the Engagement began.

• endedAt datetime The UTC date and time when the participation status of the Engagement transitioned to Completed.

• status string The participation status of the Engagement at the time of completion. This value will always be "Completed" for the Chat Script Ended event.

values Map<string, object> The response data that was collected in the Chat Engagement. See Participant data objects for details about the payload structure.

Example

{
  "type": "ChatEnded",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
    "participant": {
        "id": "151bd259-18b7-48f6-a655-713bf0192bec",
        "registeredIdentifiers": {
            "StarFinancial": "A1103451252",
            "Rival": "MDfp8Q0i"
        }
    },
    "chat": {
        "id": "9ef59d1c-5c7f-4c73-a1e1-3fedce9173e2",
        "name": "Profiling Questionnaire (Jan. 2022)"
    },
    "engagement": {
        "id": "7a7d6b80-149e-4675-92a9-c00a9433b644",
        "durationInSeconds": 372,
        "startedAt": "2022-03-09T11:30:00.323Z",
        "endedAt": "2022-03-09T11:36:12.323Z",
        "status": "Completed"
    },
    "values": {
        "Name": "John D. Rockefeller",
        "Biography": " An American business magnate and philanthropist. He is widely considered the wealthiest American of all time and the richest person in modern history.",
        "Profession": 3,
        "Bank_Account_Types": [1, 2],
        "Twitter_Account": null
    }
  }
}

Occurs when a participant subscribes for recontact in the Rival platform. This event happens after a participant provides and confirms their SMS number.

Criteria fields

None

Payload fields

participant string A unique identifier for the participant.

registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

subscriptionStatus string The subscription status of the Participant

subscriptionContext Map<string, string> A collection of key value pairs that return external values that were passed to the rival platform when the subscription occurred. These values may originate from query string parameters on a web chat or from context parameters passed into the subscription api.

Example

{
  "type": "ParticipantSubscribed",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
    "participant": "cac212ac-f99c-4f2b-9e14-b7f39266f93c",
    "registeredIdentifiers": {
      "StarFinancial": "A1103451252",
      "Rival": "MDfp8Q0i"
    },
    "subscriptionStatus": "Subscribed",
    "subscriptionContext": {
      "ttclid": "CERC3243CEWR"
    }
  }
}

Occurs when a participant is unsubscribed from the Rival platform.

Criteria fields

None

Payload fields

participant string A unique identifier for the participant.

registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

subscriptionStatus string The subscription status of the Participant

Example

{
  "type": "ParticipantUnsubscribed",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
    "participant": "cac212ac-f99c-4f2b-9e14-b7f39266f93c",
    "registeredIdentifiers": {
      "StarFinancial": "A1103451252",
      "Rival": "MDfp8Q0i"
    },
    "subscriptionStatus": "Unubscribed"
  }
}

Occurs when a Participant declines an invitation to subscribe to a Rival Community.

Criteria fields

None

Payload fields

participant string A unique identifier for the participant.

registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

subscriptionStatus string The subscription status of the Participant

Example

{
  "type": "RecontactDeclined",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
    "participant": "cac212ac-f99c-4f2b-9e14-b7f39266f93c",
    "registeredIdentifiers": {
      "StarFinancial": "A1103451252",
      "Rival": "MDfp8Q0i"
    },
    "subscriptionStatus": "Subscribed"
  }
}

Occurs when a participant responds to a Profile Attribute as part of a Chat Engagement or updated via a CSV import.

Criteria fields

attribute string An id of the Profile Attribute being subscribed to. Webhook requests will be sent for Profile Attributes that change in the associated Research Domain.

Payload fields

participant object A descriptor of the Participant that responded to the Question.

• id string A unique identifier for the Participant

• registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

attribute object A descriptor of the Profile Attribute that was updated.

• id string A unique identifier for the Profile Attribute

• type string The type of Profile Attribute - String, Decimal, DateTime, Boolean, EmailAddress, E164PhoneNumber, SingleChoice, MultipleChoice

• label string The name of the Profile Attribute, as defined in the Participant Directory.

value: string/number/array Response value/s as associated number/s or a string depending on the Attribute Type. See Participant data objects for details about the value based on the Attribute Type.

friendlyValue: string/array Response value/s for Single/Multiple Choice attribute as associated label string/s.

previousValue: string/number/array Previous response value/s as associated number/s or a string depending on the Attribute Type. This value will be null if this is the initial value for the Attribute. See Participant data objects for details about the value based on the Attribute Type.

previousFriendlyValue: string/array Previous response value/s for Single/Multiple Choice attribute as associated label string/s.

previousSetDate: string The UTC date and time when the Attribute was last updated.

Example

{
  "type": "ParticipantProfileAttributeChanged",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
      "participant": {
          "id": "151bd259-18b7-48f6-a655-713bf0192bec",
          "registeredIdentifiers": {
              "StarFinancial": "A1103451252",
              "Rival": "MDfp8Q0i"
          }
      },
      "attribute": {
          "id": "f89e8b41-b834-4a6c-95b9-176186f047c3",
          "type": "EmailAddress",
          "label": "Email",
      },
      "value": "d4@rivaltech.com",
      "previousValue": "d1@rivaltech.com",
      "previousSetDate": "1999-10-07T19:46:57Z",
  }
}

Occurs when a participant responds to any Profile Attribute as part of a Chat Engagement or updated via a CSV import.

Criteria fields

None

Payload fields

participant object A descriptor of the Participant that the Profile was updated for

• id string A unique identifier for the Participant

• registeredIdentifiers Map<string, string> A collection of third party identifiers that are associated with the participant. The key field in the map represents the name of the third party who issued the identifier. The value field represents the identifier value itself.

attribute object A descriptor of the Profile Attribute that was updated.

• id string A unique identifier for the Profile Attribute

• type string The type of Profile Attribute - String, Decimal, DateTime, Boolean, EmailAddress, E164PhoneNumber, SingleChoice, MultipleChoice

• label string The name of the Profile Attribute, as defined in the Participant Directory.

value: string/number/array Response value/s as associated number/s or a string depending on the Attribute Type. See Participant data objects for details about the value based on the Attribute Type.

friendlyValue: string/array Response value/s for Single/Multiple Choice attribute as associated label string/s.

previousValue: string/number/array Previous response value/s as associated number/s or a string depending on the Attribute Type. This value will be null if this is the initial value for the Attribute. See Participant data objects for details about the value based on the Attribute Type.

previousFriendlyValue: string/array Previous response value/s for Single/Multiple Choice attribute as associated label string/s.

previousSetDate: string The UTC date and time when the Attribute was last updated.

Example

{
  "type": "ParticipantProfileChanged",
  "id": "8039b896-dbec-452d-9072-0d0774001db6",
  "researchDomain": "10dda721-b6a6-4f5a-8e42-e022f3194003",
  "occuredAt": "2021-12-07T19:46:57Z",
  "data": {
      "participant": {
          "id": "151bd259-18b7-48f6-a655-713bf0192bec",
          "registeredIdentifiers": {
              "StarFinancial": "A1103451252",
              "Rival": "MDfp8Q0i"
          }
      },
      "attribute": {
          "id": "f89e8b41-b834-4a6c-95b9-176186f047c3",
          "type": "EmailAddress",
          "label": "Email",
      },
      "value": "d4@rivaltech.com",
      "previousValue": "d1@rivaltech.com",
      "previousSetDate": "1999-10-07T19:46:57Z",
  }
}

Occurs when a distribution message is queued to be sent to a participant.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

distribution string A descriptor of the distribution for which the distribution message is associated.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

distributionMessage object A descriptor of the distribution message sent to the participant.

• chatUrl string The personalized chat link for the participant.

• deliveryTime string Timestamp of the programmed delivery time for the distribution.

• engagementPlatform string The platform through which the chat is conducted for this participant.

• id string A unique identifier for the specific message in the distribution campaign.

• type string "Invitation" or "Reminder"

participant object A descriptor of the Participant that was the target of the distribution message.

• id string A unique identifier for the Participant

• messageAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

Example

{
  "eventType": "DistributionMessageQueued",
  "id": "392c94c2-9416-4536-82dd-741b4a309c60",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:15:44.568Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "distribution": { "type": "Invitation", "id": "c5ef7931-eaf8-403b-80c5-796e110f5775" },
    "distributionMessage": {
      "chatUrl": "chatUrl.rival.com",
      "deliveryTime": "2025-03-21T20:15:29.537Z",
      "engagementPlatform": "WebChat",
      "id": "a36f40b5-9d38-585b-954f-3d815a30b28c",
      "type": "Invitation"
    },
    "participant": {
      "id": "39b89ae5-b434-499c-94cc-2bc9f9867a16",
      "messageAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    }
  }
}

Occurs when a distribution message is sent to a participant.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chatId object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

distribution string A descriptor of the distribution for which the distribution message is associated.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

distributionMessage object A descriptor of the distribution message sent to the participant.

• id string A unique identifier for the specific message in the distribution campaign.

• type string "Invitation" or "Reminder"

participant object A descriptor of the Participant that was the target of the distribution message.

• id string A unique identifier for the Participant

• messageAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

Example

{
  "eventType": "DistributionMessageSent",
  "id": "a5fe6afa-1968-4ae3-926f-5d8c262099f7",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:48.726Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "distribution": { "type": "Invitation", "id": "c5ef7931-eaf8-403b-80c5-796e110f5775" },
    "distributionMessage": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "participant": {
      "id": "39b89ae5-b434-499c-94cc-2bc9f9867a16",
      "messageAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    },
    "trackingId": "a36f40b5-9d38-585b-954f-3d815a30b28c"
  }
}

Occurs when a distribution message is delivered to a participant.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

distribution string A descriptor of the distribution for which the distribution message is associated.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

distributionMessage object A descriptor of the distribution message sent to the participant.

• id string A unique identifier for the specific message in the distribution campaign.

• type string "Invitation" or "Reminder"

participant object A descriptor of the Participant that was the target of the distribution message.

• id string A unique identifier for the Participant

• messageAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

deliveredAt string Timestamp for delivery to participant.

Example

{
  "eventType": "DistributionMessageDelivered",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "distribution": { "type": "Invitation", "id": "c5ef7931-eaf8-403b-80c5-796e110f5775" },
    "distributionMessage": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "participant": {
      "id": "39b89ae5-b434-499c-94cc-2bc9f9867a16",
      "messageAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    },
    "deliveredAt": "2025-03-21T20:16:50.805Z",
  }
}

Occurs when a distribution message begins delivery by the third party platform.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

distribution string A descriptor of the distribution for which the distribution message is associated.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

message object A descriptor of the distribution message sent to the participant.

• dateSent string Timestamp for send time of message.

• parts array All parts of the message being sent to the participant.

• toAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

participant object A descriptor of the Participant that was the target of the distribution message.

• id string A unique identifier for the Participant

• messageAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

Example

{
  "eventType": "DeliverDistributionMessageStarted",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "distribution": { "type": "Invitation", "id": "c5ef7931-eaf8-403b-80c5-796e110f5775" },
    "distributionMessage": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "message": {
      "dateSent": "2025-03-06T19:23:38.111Z",
      "parts": [
          {
            "content": "You’ve been invited to a chat with {{ResearchDomain.Brand.Name}}. Click to start the engagement in your web browser. {{Chat URL}}",
            "type": "Text"
          }
      ],
      "toAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    },
    "participant": {
      "id": "39b89ae5-b434-499c-94cc-2bc9f9867a16",
      "messageAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    },
    "deliveredAt": "2025-03-21T20:16:50.805Z",
  }
}

Occurs when a distribution message delivery by the third party platform fails.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

distributionMessage object A descriptor of the distribution message sent to the participant.

• id string A unique identifier for the specific message in the distribution campaign.

• type string "Invitation" or "Reminder"

participant object A descriptor of the Participant that was the target of the distribution message.

• id string A unique identifier for the Participant

• messageAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

Example

{
  "eventType": "DeliverDistributionMessageFailed",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "distributionMessage": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "participant": {
      "id": "39b89ae5-b434-499c-94cc-2bc9f9867a16",
      "messageAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
  }
}

Occurs when a distribution message delivery is canceled.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

distributionMessage object A descriptor of the distribution message sent to the participant.

• id string A unique identifier for the specific message in the distribution campaign.

• type string "Invitation" or "Reminder"

participant object A descriptor of the Participant that was the target of the distribution message.

• id string A unique identifier for the Participant

• messageAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

Example

{
  "eventType": "DeliverDistributionMessageCanceled",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "distributionMessage": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "participant": {
      "id": "39b89ae5-b434-499c-94cc-2bc9f9867a16",
      "messageAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
  }
}

Occurs when a distribution message delivery by the third party platform is unconfirmed.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

distributionMessage object A descriptor of the distribution message sent to the participant.

• id string A unique identifier for the specific message in the distribution campaign.

• type string "Invitation" or "Reminder"

participant object A descriptor of the Participant that was the target of the distribution message.

• id string A unique identifier for the Participant

• messageAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

Example

{
  "eventType": "DeliverDistributionMessageUnconfirmed",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "distributionMessage": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "participant": {
      "id": "39b89ae5-b434-499c-94cc-2bc9f9867a16",
      "messageAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
  }
}

Occurs when a distribution message fails to be queued for sending.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

distributionMessage object A descriptor of the distribution message sent to the participant.

• id string A unique identifier for the specific message in the distribution campaign.

• type string "Invitation" or "Reminder"

participant object A descriptor of the Participant that was the target of the distribution message.

• id string A unique identifier for the Participant

• messageAddress object A descriptor of the protocol, platform and address through which the distribution message is being sent to the participant.

  • messagePlatform string Platform through which the message is distributed.

  • messageProtocol string Protocol through which the message is distributed.

  • value string Message address value.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

Example

{
  "eventType": "FailedDistributionMessageQueued",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "distributionMessage": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "participant": {
      "id": "39b89ae5-b434-499c-94cc-2bc9f9867a16",
      "messageAddress": {
        "messagePlatform": "Twilio",
        "messageProtocol": "SMS",
        "value": "+11111111111"
      }
    },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
  }
}

Occurs when a distribution delivery plan job begins (either manually or scheduled).

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

statistics object A collection of statistics related to the messages being queued as part of the delivery plan.

• numberMessagesQueued number

• numberTimesStarted number

Example

{
  "eventType": "JobDeliveryPlanStarted",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "statistics": {
      "numberMessagesQueued": 4,
      "numberTimesStarted": 1
    },
  }
}

Occurs when a distribution delivery plan job completes.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

statistics object A collection of statistics related to the messages being queued as part of the delivery plan.

• numberMessagesCanceled number

• numberMessagesDelivered number

• numberMessagesSendingFailed number

• numberMessagesDeliveringFailed number

Example

{
  "eventType": "JobDeliveryPlanFinished",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "statistics": {
      "numberMessagesCanceled": 2,
      "numberMessagesDelivered": 8,
      "numberMessagesSendingFailed": 1,
      "numberMessagesDeliveringFailed": 1
    },
  }
}

Occurs when a distribution delivery plan job completes.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

statistics object A collection of statistics related to the messages being queued as part of the delivery plan.

• numberMessagesQueued number

• numberMessagesCanceled number

• numberMessagesSending number

• numberMessagesDelivering number

• numberMessagesDelivered number

• numberMessagesDeliveryUnconfirmed number

• numberMessagesSendingFailed number

• numberMessagesDeliveringFailed number

Example

{
  "eventType": "JobDeliveryPlanCanceled",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" },
    "statistics": {
      "numberMessagesQueued": 2,
      "numberMessagesCanceled": 8,
      "numberMessagesSending": 1,
      "numberMessagesDelivering": 1,
      "numberMessagesDelivered": 2,
      "numberMessagesDeliveryUnconfirmed": 1,
      "numberMessagesSendingFailed": 1,
      "numberMessagesDeliveringFailed": 1
    },
  }
}

Occurs when a distribution delivery plan job completes.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

Example

{
  "eventType": "EventDeliveryPlanEnabled",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" }
  }
}

Occurs when a distribution delivery plan job completes.

Criteria fields

chat string An id for a chat in the current research domain. Webhook requests will be sent for a distribution that belogns to this chat.

distributionType string The type of distribution for which webhook requests will be sent ("Invitation" or "Reminder").

distribution string An id for the specific distribution for which webhook requests will be sent.

Payload fields

chat object A descriptor of the Chat that was distributed.

• id string A unique identifier for the Chat.

targetedDistribution string Timestamp for delivery to participant.

• type string "Invitation" or "Reminder"

• id string A unique identifier for the distribution.

Example

{
  "eventType": "EventDeliveryPlanDisabled",
  "id": "13982e16-27e7-4955-b2be-25403b7d2c74",
  "researchDomain": "2fbeb79b-ee5d-4bf9-99f0-56c37d166c8a",
  "occuredAt": "2025-03-21T20:16:52.073Z",
  "data": {
    "chat": { "id": "06eec327-157b-4986-ae46-4ed459e6c145" },
    "targetedDistribution": { "id": "a36f40b5-9d38-585b-954f-3d815a30b28c", "type": "Invitation" }
  }
}