API Examples
This page contains examples of how to represent different interactions using the Interactions API
Note: this page focuses on examples of interactions using the MVP data model for the Interactions API. For other accepted data formats, please see the API Reference section.
Context of the Interaction
Joan Smith is a voter in Massachusetts being contacted by David Harris, a volunteer, as part of an event build for a rally for Poppy for Governor. David has also been trained to record information on Joan's support for the candidate and willingness to volunteer at the event.
David is using Blue Text, an outreach tool, to reach out to Joan's cell phone. When Blue Text receives a list of phone numbers that includes Joan Smith's number, it also receives multiple IDs for Joan Smith to help with data tracking: a CRM id 1234, a Secretary of State (SOS) id 3456, and a "Poppy for Governor" id 5678 that the campaign uses for analytics. Blue Text does not have its own id for Joan and instead uses Joan's phone number as a primary identifier.
Blue Text has a mapping of David Harris's CRM id 7890 to its own user id for David. When Blue Text shares the results of the conversation, it includes David's CRM id and lists David as the canvasser. Blue Text also has a mapping of Poppy for Governor's account within Blue Text to committee in CRM, and includes the CRM's committee 78 in the results of the conversation.
Blue Text has integrated with the VAN API and surfaces activist codes and survey questions/responses within its application for user convenience. It can also include additional details around event scheduling in unstructured formats.
Scenarios
Scenario 1: Joan does not reply
The outcome will be no_answer. Blue Text will still be able to include some information on the event in the jsonMetadata.
{
"interactions": [
{
"person": [
{
"id": "1234",
"type": "CRM"
},
{
"id": "3456",
"type": "SOS"
},
{
"id": "5678",
"type": "Poppy for Governor"
}
],
"stateCode": "MA",
"channel": {
"type": "phone_call",
"value": "15556789210"
},
"attemptDatetime": "2025-09-03T14:21:34.891Z",
"method": "text",
"committee": [
{
"type": "MyCRM",
"id": "poppy-for-governor"
}
],
"canvasser": [
{
"type": "crm_id",
"id":"7890"
}
],
"vendorSource": "Blue Text",
"outcome": "no_answer",
"jsonMetadata": "{ \"event\": \"weekend rally cambridge\" }"
}
]
}Scenario 2: Joan replies that she can't make it (logged in json_metadata)
David was able to reach Joan, so the contact will be logged as a successful_contact. The RSVP of the conversation is recorded in the jsonMetadata.
{
"interactions": [
{
"person": [
{
"id": "1234",
"type": "CRM"
},
{
"id": "3456",
"type": "SOS"
},
{
"id": "5678",
"type": "Poppy for Governor"
}
],
"stateCode": "MA",
"channel": {
"type": "phone_call",
"value": "15556789210"
},
"attemptDatetime": "2025-09-03T14:21:34.891Z",
"method": "text",
"committee": [
{
"type": "MyCRM",
"id": "poppy-for-governor"
}
],
"canvasser": [
{
"type": "crm_id",
"id": "7890"
}
],
"vendorSource": "Blue Text",
"outcome": "successful_contact",
"jsonMetadata": "{\n \"event\": \"weekend canvass cambridge\",\n \"rsvp\": \"no\"\n}"
}
]
}Scenario 3: Joan replies that she can't make it (logged in json_metadata and as a survey_response)
Blue Text retrieved the survey_question and survey_response metadata from VAN and includes these as an object in the outcomesDetailed field.
{
"interactions": [
{
"person": [
{
"id": "1234",
"type": "CRM"
},
{
"id": "3456",
"type": "SOS"
},
{
"id": "5678",
"type": "Poppy for Governor"
}
],
"stateCode": "MA",
"channel": {
"type": "phone_call",
"value": "15556789210"
},
"attemptDatetime": "2025-09-03T14:21:34.891Z",
"method": "text",
"committee": [
{
"type": "MyCRM",
"id": "poppy-for-governor"
}
],
"canvasser": [
{
"type": "crm_id",
"id": "7890"
}
],
"vendorSource": "Blue Text",
"outcome": "successful_contact",
"outcomesDetailed": [
{
"type": "survey_response",
"value": {
"questionText": "Are you able to attend the Weekend Rally in Cambridge?",
"questionId": "765",
"responseText": "No",
"responseId": "41"
}
}
],
"jsonMetadata": "{\n \"event\": \"weekend canvass cambridge\",\n \"rsvp\": \"no\"\n}"
}
]
}Scenario 4: Joan replies that she can make it and wants to volunteer with the campaign
Blue Text would change the values in the outcomesDetailed object and metadataJson. Blue Text would also include an activist_code object signifying that Joan wants to volunteer in the outcomesDetailed and would include the activist_code_id from VAN. David also wrote a note in his Blue Text conversation that Joan was specifically interested in canvassing and helping out at other events in the future which Blue Text includes in the jsonMetadata.
{
"interactions": [
{
"person": [
{
"id": "1234",
"type": "CRM"
},
{
"id": "3456",
"type": "SOS"
},
{
"id": "5678",
"type": "Poppy for Governor"
}
],
"stateCode": "MA",
"channel": {
"type": "phone_call",
"value": "15556789210"
},
"attemptDatetime": "2025-09-03T14:21:34.891Z",
"method": "text",
"committee": [
{
"type": "MyCRM",
"id": "poppy-for-governor"
}
],
"canvasser": [
{
"type": "crm_id",
"id": "7890"
}
],
"vendorSource": "Blue Text",
"outcome": "successful_contact",
"outcomesDetailed": [
{
"type": "survey_response",
"value": {
"questionText": "Are you able to attend the Weekend Rally in Cambridge?",
"questionId": "765",
"responseText": "No",
"responseId": "41"
}
},
{
"type": "activist_code",
"value": {
"activistCodeId": "12",
"text": "12"
}
}
],
"jsonMetadata": "{\n \"event\": \"weekend canvass cambridge\",\n \"rsvp\": \"yes\",\n \"note\": \"interested in canvassing and volunteering at events\"\n}"
}
]
}Scenario 5: Joan replies that she can make it and wants to volunteer with the campaign but also wants to be opted out of future text messages (contains 2 interactions)
Blue Text can send multiple interactions in the request: one that is the same as the request in Scenario 5, and another that is similar to Scenario 1 but with the outcome field as opted_out
{
"interactions": [
{
"person": [
{
"id": "1234",
"type": "CRM"
},
{
"id": "3456",
"type": "SOS"
},
{
"id": "5678",
"type": "Poppy for Governor"
}
],
"stateCode": "MA",
"channel": {
"type": "phone_call",
"value": "15556789210"
},
"attemptDatetime": "2025-09-03T14:21:34.891Z",
"method": "text",
"committee": [
{
"type": "MyCRM",
"id": "poppy-for-governor"
}
],
"canvasser": [
{
"type": "crm_id",
"id": "7890"
}
],
"vendorSource": "Blue Text",
"outcome": "successful_contact",
"outcomesDetailed": [
{
"type": "survey_response",
"value": {
"questionText": "Are you able to attend the Weekend Rally in Cambridge?",
"questionId": "765",
"responseText": "No",
"responseId": "41"
}
},
{
"type": "activist_code",
"value": {
"activistCodeId": "12",
"text": "12"
}
}
],
"jsonMetadata": "{\n \"event\": \"weekend canvass cambridge\",\n \"rsvp\": \"yes\",\n \"note\": \"interested in canvassing and volunteering at events\"\n}"
},
{
"person": [
{
"id": "1234",
"type": "CRM"
},
{
"id": "3456",
"type": "SOS"
},
{
"id": "5678",
"type": "Poppy for Governor"
}
],
"stateCode": "MA",
"channel": {
"type": "phone_call",
"value": "15556789210"
},
"attemptDatetime": "2025-09-03T14:21:34.891Z",
"method": "text",
"committee": [
{
"type": "MyCRM",
"id": "poppy-for-governor"
}
],
"canvasser": [
{
"type": "crm_id",
"id": "7890"
}
],
"vendorSource": "Blue Text",
"outcome": "opted_out",
"jsonMetadata": "{\n \"event\": \"weekend rally cambridge\"\n}"
}
]
}Updated 21 days ago