Bulk Outreach Extract API
Overview of Outreach Integration
You can streamline outreach initiatives with the Civitas Learning Bulk Outreach Extract API. The Bulk Outreach Extract API allows you to programmatically retrieve outreach data from Civitas applications in an ongoing manner.
This includes outreach efforts initiated in these applications:
- Analytics (Illume)
- Inspire for Advisors
- Inspire for Faculty
You can use this API to integrate outreach data with third-party systems. For example, you may:
- Add it to a centralized system, to coordinate communications across campus
- Connect it to a CRM (such as Salesforce), to prevent users from having to double-log outreach
How it works
The API works by creating a pipeline between Civitas’ database and a secure message queue where you can retrieve all of your outreach data, executed from Civitas applications:
- Email campaigns
- Nudge campaigns
This data is available in the queue within minutes of being sent from an application. By developing a client queue, you can pull message data from the queue environment and use this data in a way that works best for your institution.
Getting Started
Step 1: Before you can access the queue, you must provide us with a list of whitelist IP addresses. Send this information to Support to get started. Once we have received the IP addresses, we will:
- setup a staging queue with sample message data,
- provide you with a url for the queue,
- provide you with a username and password to access your account, and
- provide you with the name of the queue to retrieve your data.
Note: We can whitelist more than one IP address and we can whitelist IP ranges, within reason.
Step 2: Once you can connect to the queue, you will need to develop a client to consume your message data. For information on how to create a client of the queue, see the Amazon-mq documentation. Details about Civitas message format and examples of outreach properties are available beginning on page 2.
Step 3: Use the staging queue to validate that your client is consuming messages. Each message can only be retrieved once from the message queue. After a message has been retrieved from the queue, it cannot be retrieved again as it no longer exists in the queue environment.
Step 4: Once your client has been validated in the staging environment, contact Support.
Message Format
There are a number of properties included in the data for each message. Common properties exist across all applications for message, student, and outreach properties. Email properties, such as message content & context are mapped within the name, value, & valueId of outreach properties. Use the links below to review common fields for each property.
- Common Message Properties
- Common Student Properties
- Common Outreach Properties
- Common Email Properties
- Non-Email Related Outreach Properties
Common Message Properties
| Description | Property Name(s) | Examples of Property Values |
|---|---|---|
| Creation date | createdAt | 2018-06-11T19:35:15.366848 |
| Contact information for the employee who executed the outreach | employeeFirstName, employeeLastName, employeeEmail | Joe, Bob, joe.bob@institution.edu |
| Civitas application | outreachSource | Illume Students, Faculty, Advisor |
| Outreach type | outreachMedium | Email, Campaign, Text, Appointment |
*Note: Illume Students = Analytics, Faculty = IFA – Inspire for Faculty, Advisor = IFA – Inspire for Advisors
Common Student Properties
An outreach can include many student recipients.
| Description | Property Name(s) | Examples of Property Values |
|---|---|---|
| Student ID number | institutionPersonID | 123567 |
| Student name | firstName, lastName | Scarlett, Jones |
| Student email address | emailAddress | scarlett.jones@institution.edu |
| Creation date | createdAt | 2018-06-11T21:07:44.222117 |
Common Outreach Properties
An outreach can include many outreach properties. Outreach properties will vary based on the application source and type. Outreach properties will include the following fields:
- outreachPropertyId
- outreachId
- name
- value
- valueId
- createdAt
Common Email Properties
Details about emails sent through civitas systems will be provided as Outreach Properties
| Description | Property Name(s) | Examples of Property Values |
|---|---|---|
| Message content | emailMessage | Dear [Student Firstname], Test sending an outreach. Thanks, Trey Smith |
| Subject line | emailSubject | Student success test message |
| Sender email for the outreach | emailSenderAddress | fakestuff@institution.com |
| Sender name for the outreach | emailSenderFirstName, emailSenderLastName | Bharathi, Garcia |
Non-Email Related Outreach Properties
Non-email related details sent through Civitas will be provided as Outreach Properties:
| Description | Property Name(s) | Examples of Property Values |
|---|---|---|
| Outreach Result | outreachMediumResult | Appointment scheduled Campaign sent Email sent Left voicemail Other Text message sent Wrong number |
| Reason for Outreach | outreachReason | GPA Inspiration/Intervention Factors Persistence Probability Shift Student Hold |
| Recommendation or Referral made | outreachRecommendation | Other Referred to Financial Aid Referred to Tutoring |
| Topic Discussed | outreachTopic | Academic Intervention/Inspiration Factors Personal Financial |
| Individual that initiated the outreach | outreachInitator | Advisor Initiated Faculty Initiated Student Initiated |
Note: If you have trouble locating a specific value, try to find it using the valueId. The label or name of a value can change, but its valueId will never change. Consider the following example:
Say there’s a property with a name like “Outreach Reason”, and a value like “Bad GPA”, and a valueID of “123456”. It’s possible that someone decided to change “Bad GPA” to “GPA below threshold”. Now, new outreaches stored in the outreach service would have a value of “GPA below threshold”, but the valueID wouldn’t change. It would still be “123456”.
Reference the sample JSON responses to see additional examples of how email properties may appear in your data.
Analytics Outreach Properties Example
"outreachProperties": [
{
"outreachPropertyId": 18 ,
"outreachId": "5751e799-1725-45c7-a2bd-1b40b43bd8aa" ,
"name": "isAttrition" ,
"value": "0" ,
"createdAt": "2018-06-11T19:35:15.366848"
},
{
"outreachPropertyId": 16 ,
"outreachId": "5751e799-1725-45c7-a2bd-1b40b43bd8aa" ,
"name": "campaignName" ,
"value": "Trey Sample Illume Campaign" ,
"valueId": "6260e21e-35a6-4142-96b3-f8da51a95a9c" ,
"createdAt": "2018-06-11T19:35:15.366848"
},
{
"outreachPropertyId": 14 ,
"outreachId": "5751e799-1725-45c7-a2bd-1b40b43bd8aa" ,
"name": "outreachMediumResult" ,
"value": "Campaign sent" ,
"valueId": "c9a33a36-4cb0-2c42-352c-75e2911e2f27" ,
"createdAt": "2018-06-11T19:35:15.366848"
},
{
"outreachPropertyId": 19 ,
"outreachId": "5751e799-1725-45c7-a2bd-1b40b43bd8aa" ,
"name": "durationInMs" ,
"value": "0" ,
"createdAt": "2018-06-11T19:35:15.366848"
},
{
"outreachPropertyId": 15 ,
"outreachId": "5751e799-1725-45c7-a2bd-1b40b43bd8aa" ,
"name": "outreachInitiator" ,
"value": "Advisor Initiated" ,
"valueId": "edc3b021-02f8-4e52-9980-e1f5fd6b89bc" ,
"createdAt": "2018-06-11T19:35:15.366848"
},
{
"outreachPropertyId": 17 ,
"outreachId": "5751e799-1725-45c7-a2bd-1b40b43bd8aa" ,
"name": "isSuccess" ,
"value": "1" ,
"createdAt": "2018-06-11T19:35:15.366848"
}
],IFA Outreach Properties Example
"outreachProperties": [
{
"outreachPropertyId": 6,
"outreachId": "0ecba66b-a31c-40d9-b95c-cd6ff309d43b",
"name": "outreachMediumResult",
"value": "Text message sent",
"valueId": "c95267ff-2718-f2d3-1cd1-38f2f2bad8da",
"createdAt": "2018-06-11T19:14:34.391597"
},
{
"outreachPropertyId": 8,
"outreachId": "0ecba66b-a31c-40d9-b95c-cd6ff309d43b",
"name": "isAttrition",
"value": "0",
"createdAt": "2018-06-11T19:14:34.391597"
},
{
"outreachPropertyId": 7,
"outreachId": "0ecba66b-a31c-40d9-b95c-cd6ff309d43b",
"name": "outreachInitiator",
"value": "Student Initiated",
"valueId": "cd77b7bf-e5a2-4368-94e1-e7c01f687b09",
"createdAt": "2018-06-11T19:14:34.391597"
},
{
"outreachPropertyId": 5,
"outreachId": "0ecba66b-a31c-40d9-b95c-cd6ff309d43b",
"name": "outreachRecommendation",
"value": "Referred to Financial Aid",
"createdAt": "2018-06-11T19:14:34.391597"
},
{
"outreachPropertyId": 4,
"outreachId": "0ecba66b-a31c-40d9-b95c-cd6ff309d43b",
"name": "outreachTopic",
"value": "Academic",
"createdAt": "2018-06-11T19:14:34.391597"
},
{
"outreachPropertyId": 9,
"outreachId": "0ecba66b-a31c-40d9-b95c-cd6ff309d43b",
"name": "outreachReason",
"value": "Student Hold",
"createdAt": "2018-06-11T19:14:34.391597"
}
], IFF Outreach Properties Example
"outreachProperties": [
{
"outreachPropertyId": 12,
"outreachId": "8a007dbb-23eb-4889-9afb-d7b20586ea47",
"name": "isAttrition",
"value": "0",
"createdAt": "2018-06-11T19:30:23.473274"
},
{
"outreachPropertyId": 10,
"outreachId": "8a007dbb-23eb-4889-9afb-d7b20586ea47",
"name": "outreachInitiator",
"value": "Faculty Initiated",
"valueId": "07e0f3dd-1673-8244-2364-b95f97bbf13e",
"createdAt": "2018-06-11T19:30:23.473274"
},
{
"outreachPropertyId": 13,
"outreachId": "8a007dbb-23eb-4889-9afb-d7b20586ea47",
"name": "outreachMediumResult",
"value": "Email sent",
"valueId": "5bb6226a-5db7-69b7-2054-0b7a725e045a",
"createdAt": "2018-06-11T19:30:23.473274"
},
{
"outreachPropertyId": 11,
"outreachId": "8a007dbb-23eb-4889-9afb-d7b20586ea47",
"name": "rawEnrollmentId",
"value": "35776743",
"createdAt": "2018-06-11T19:30:23.473274"
}
],