Overview

Each item in outcomesDetailed includes a required operation field that indicates whether the outcomeDetail is being created or deleted. This defaults to "create".

Valid values are create and delete

Operations for Individual OutcomeDetails

An interaction represents something that happened, e.g. a conversation, an SMS response, etc. The operation field describes what kind of data change an outcome represents.

For example, a voter removing a text message opt-out is a new interaction (something happened), but its effect will change the prior opt-in/opt-out status to unknown. That interaction would use "operation": "delete" on the relevant outcome detail.

Subsequent interactions match by Person

Interactions calls that add an outcomeDetail or delete an outcomeDetail from a previous interaction do so by creating a new interaction with a new interactionId for the same set of Person identifiers. They do not overwrite or alter a previous interaction by interactionId.

Downstream destinations are responsible for deciding how they want to handle interactions sent for the same person with new or altered information.

Idempotency via Interaction IDs

Sending interactions with the same interaction ID is intended to allow requests to be idempotent, not to update an existing interaction. Sending the same interaction ID with different contents is unsupported behavior; destinations will receive the interaction but will either reject it or handle it unpredictably, so you should avoid re-sending interactions with the same ID but different bodies, except in the exception defined below.

Exception for VAN /canvassResponses destination

The only exception is that Interactions can be re-sent with different values when targeting VAN as a destination when the initial request fails due to a validation failure and you must make updates.

Examples

Creating an outcome (default behavior)

A volunteer speaks with a voter and records a new activist code. This is the default behavior: "operation": "create" can be included explicitly or omitted.

{
  "interactions": [
    {
      "person": [{ "id": "1234", "type": "CRM" }],
      "stateCode": "MA",
      "method": "phone",
      "outcome": "successful_contact",
      "outcomesDetailed": [
        {
          "operation": "create",
          "type": "activist_code",
          "activistCodeId": "42",
          "text": "Event Volunteer"
        }
      ]
    }
  ]
}

Deleting an outcome

E.g. A voter undoes their opt-out from an SMS list, changing their previous status to unknown.

{
  "interactions": [
    {
      "person": [{ "id": "1234", "type": "CRM" }],
      "stateCode": "MA",
      "method": "text",
      "outcome": "successful_contact",
      "outcomesDetailed": [
        {
          "operation": "delete",
          "type": "communication_consent",
          "consentStatus": "opted_out"
        }
      ]
    }
  ]
}

Mixing operations in a single interaction

A single conversation can produce multiple outcome changes. Here, a volunteer learns learns that a voter wants to rescind their communications opt-out, and adds a new note about their interaction.

{
  "interactions": [
    {
      "person": [{ "id": "1234", "type": "CRM" }],
      "stateCode": "MA",
      "method": "phone",
      "outcome": "successful_contact",
      "outcomesDetailed": [
        {
          "operation": "delete",
          "type": "communication_consent",
          "consentStatus": "opted_out"
        },
        {
          "operation": "create",
          "type": "contact_note",
          "value": {
						"content": "my new note contents",
					}
        }
      ]
    }
  ]
}

Data edits from a CRM

A CRM user corrects a voter's record through the UI. They delete a survey response for a given response ID and send a new one with a new value.

{
  "interactions": [
    {
      "person": [{ "id": "1234", "type": "MY_CRM" }],
      "stateCode": "MA",
      "method": "direct_edit",
      "outcome": "data_change",
      "outcomesDetailed": [
        {
          "operation": "delete",
          "type": "survey_response",
          "questionId": "100",
          "responseId": "305",
        }
      ]
    }
  ]

{
  "interactions": [
    {
      "person": [{ "id": "1234", "type": "MY_CRM" }],
      "stateCode": "MA",
      "method": "direct_edit",
      "outcome": "data_change",
      "outcomesDetailed": [
        {
          "operation": "create",
          "type": "survey_response",
          "questionId": "100",
          "questionText": "Preferred contact method",
          "responseId": "305",
          "responseText": "Email"
        }
      ]
    }
  ]
}