Register External User Events

Updated Sep 23, 2026Article

URL#

json

POST https://{{client}}.api.451.io/v2/analytics/events

About#

The Events API request allows you to register external user events into Element451. Each event sent will be validated and processed in isolation, if some events fail validation or processing those will not affect good events which will be registered.

General Parameters#

"events": The list of events, and supporting details, you want to register into Element. The required fields depend on which type of event is sent, and are listed under the corresponding headers below.
- “type”: “string” - (required) The current external events include:
  - “ActivityCompleted”.
  - CourseEnrolled
  - CourseDropped
  - CourseCompleted
  - CourseUpdated
  - CourseFailed

Example - ActivityComplete User Event

ActivityCompleted allows for custom activity events from outside Element451 to be added to the activity logs.

Parameters:

“activity_type” : “guid” - (Required) The activity type requires a type guid. These can be found using the “../users/notes/types/?. (opens in a new tab).” api call.
“user_id” : “string - (Required if identities is not used) The Element451 ID to associate the activity with.
“timestamp” : “string” - (Optional) The epoch timestamp.
“name” : “string” - (Optional) The name of the activity.
“note” : “string” - (Optional) A note that provides more details about the activity.
“actor_id” : “string” - (Optional) The internal (staff) user ID that the activity should be associated with.
“assigned_to” : “string” - (Optional) The internal (staff) user ID that the activity was assigned to.
“identities”: “array” - (required if user_id is not used) An array of identity objects. This can be used for any external event when the user_id is unknown.
- “type” : “string” - The type of identity that is being sent. These include: phone, email, and identity type listed in Element451 (e.g. SCHOOL_ID, COMMONAPP_ID )
- “id” : “string” - The corresponding identity to match

Example

json

Request:
POST https://{{client}}.api.451.io/v2/analytics/events

URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.

Request headers:
Feature: Feature token for that client
Content-Type: 'application/json'

Request body parameters:
{
    "events" : [
        {
            "type": "ActivityCompleted",
            "activity_type" : "example.taxonomy.451",
            "name": "PhoneCallLog",
            "timestamp": 618395780,
            "note": "Had call with student",
            "user_id": "5702ec092e402e851a8b4567",
            "actor_id" : "620d4f7582d068426401eb36"
        },
        {
            "type": "ActivityCompleted",
            "activity_type" : "example.taxonomy.451",
            "name": "PhoneCallLog",
            "timestamp": 618395790,
            "note": "No answer",
            "actor_id" : "620d4f7582d068426401eb36",
            "identities":[
                {
                  "type":"phone",
                  "id":"+19873210654"
                }
            ]
        }
    ]
}

Expected Response:
Status 202
{
    "data": [
        {
            "index": 0,
            "status": "accepted"
        },
        {
            "index": 1,
            "status": "accepted"
        }
    ]
}

Example - Course User Events

Course activity events can be added from external systems using the events API. Many of the fields are text based and can be customized to your institutional needs, though examples are listed below.

Parameters

"type": “string” - (Required) Course events include “CourseCompleted”, “CourseDropped”, “CourseEnrolled”, and “CourseUpdated”.
"course_guid" : “guid” - (Required) The course GUID from the Courses data source. This is used to link the course title to the course event action.
"user_id": “string” - (Required) The Element451 contact record ID that the course event should be associated with.
"timestamp": “second timestamp” - (Optional) The starting date for course. (eg. 1686774298)
"subject": “string” - (Optional) The course Subject. (e.g. BIO, CHEM)
"number" : “string” - (Optional) The numerical identifier for the course level. (e.g. 101, 402)
"academic_unit" : “string” - (Optional) The department that is offering the course
"method" : “string” - (Optional) The method of course delivery.(e.g. asynchronous online, synchronous online, in-person, hybrid)
"course_type" : “string” - (optional) The type of course delivery (e.g. lecture, lab, discussion)
"credit" : “string” - (Optional) The number of credit hours awarded. (e.g 0, 3).
"grading" : “string” - (Optional) The grading scale of the course. (e.g. Pass/Fail, A-F, 100-0)
"parent_term" : “string” - (Optional) The term in which the course is taught. (e.g. Fall 2022, Spring 2023.)
"term" : “string” - (Optional) The sub-term in which the course is taught. (e.g. 1, A, 7WK1, 5WK2)
"start_date" : “millisecond timestamp” - (Optional) The starting date for the course. (eg. 1686774298000)
"end_date" : “millisecond timestamp” - (Optional) The ending date for the course. (eg. 1686774298000)
"schedule" : “string” - (Optional) The days of delivery. (e.g. MWF, TR, F.)
"time” : “string” - (Optional) The time of delivery. (e.g. 1400-1500)
"source": “string” - (Optional) The source of the course. (e.g. Banner, edX, SIS)

The following two are optional for specific events.

"student_grade": “string” - (Optional, only for courseCompleted and courseUpdated) The grade with which the student completed the course or currently has.
“dropped_reason” : “string” - (Optional, only for courseDropped) The reason why student dropped the course.
“failed_reason” : “string” - (Optional, only for courseFailed) The reason why student failed the course.

Example - courseEnrolled

json

Request:
POST https://{{client}}.api.451.io/v2/analytics/events

URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.

Request headers:
Feature: Feature token for that client
Content-Type: 'application/json'

Request body parameters:
{
    "events" : [
        {   "type": "courseEnrolled",
            "course_guid" : "demo.courses.45",
            "user_id": "5cdb0a5366a4f637d56b3711",
            "source": "Ethos",
            "timestamp": 1671118910,
            "subject": "CSV",
            "number" : "101",
            "method" : "Online",
            "credit" : "3",
            "grading" : "A-F",
            "parent_term" : "Fall 2022",
            "term" : "1",
            "start_date" : "1664638910",
            "end_date" : "1671118910",
            "schedule" : "MWF",
            "course_time" : "800-900"
        }
    ]
}

Expected Response:
Status 202
{
    "data": [
        {
            "index": 0,
            "status": "accepted"
        }
    ]
}

Example - courseCompleted

json

Request:
POST https://{{client}}.api.451.io/v2/analytics/events

URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.

Request headers:
Feature: Feature token for that client
Content-Type: 'application/json'

Request body parameters:
{
    "events" : [
        {   "type": "courseCompleted",
            "course_guid" : "demo.courses.45",
            "user_id": "5cdb0a5366a4f637d56b3711",
            "source": "Ethos",
            "student_grade": "A",
            "timestamp": 1671118910,
            "subject": "CSV",
            "number" : "101",
            "method" : "Online",
            "credit" : "3",
            "grading" : "A-F",
            "parent_term" : "Fall 2022",
            "term" : "1",
            "start_date" : "1664638910",
            "end_date" : "1671118910",
            "schedule" : "MWF",
            "course_time" : "800-900"
        }
    ]
}

Expected Response:
Status 202
{
    "data": [
        {
            "index": 0,
            "status": "accepted"
        }
    ]
}

Example - courseDropped

json

Request:
POST https://{{client}}.api.451.io/v2/analytics/events

URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.

Request headers:
Feature: Feature token for that client
Content-Type: 'application/json'

Request body parameters:
{
    "events" : [
        {   "type": "courseDropped",
            "course_guid" : "demo.courses.45",
            "user_id": "5cdb0a5366a4f637d56b3711",
            "source": "Ethos",
            "timestamp": 1671118910,
            "subject": "CSV",
            "number" : "101",
            "method" : "Online",
            "credit" : "3",
            "grading" : "A-F",
            "parent_term" : "Fall 2022",
            "term" : "1",
            "start_date" : "1664638910",
            "end_date" : "1671118910",
            "schedule" : "MWF",
            "course_time" : "800-900"
        }
    ]
}

Expected Response:
Status 202
{
    "data": [
        {
            "index": 0,
            "status": "accepted"
        }
    ]
}

Example - courseUpdated

json

Request:
POST https://{{client}}.api.451.io/v2/analytics/events

URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.

Request headers:
Feature: Feature token for that client
Content-Type: 'application/json'

Request body parameters:
{
    "events" : [
        {   "type": "courseUpdated",
            "course_guid" : "demo.courses.45",
            "user_id": "5cdb0a5366a4f637d56b3711",
            "source": "Ethos",
            "student_grade": "B",
            "timestamp": 1671118910,
            "subject": "CSV",
            "number" : "101",
            "method" : "Online",
            "credit" : "3",
            "grading" : "A-F",
            "parent_term" : "Fall 2022",
            "term" : "1",
            "start_date" : "1664638910",
            "end_date" : "1671118910",
            "schedule" : "MWF",
            "course_time" : "800-900"
        }
    ]
}

Expected Response:
Status 202
{
    "data": [
        {
            "index": 0,
            "status": "accepted"
        }
    ]
}