Inviting Students to a Degree using API

This guide explains how colleges using Canvas or other systems can utilize the addStudentToDegree. This API mutation can be used to invite students to degrees, avoid account duplication, and ensure accurate billing and payment tracking.

Key Concepts

1. Use External ID to Prevent Account Duplication

What is External ID?
External ID refers to a unique, unchangeable identifier for students (e.g., Canvas User ID). It ensures each student is accurately identified across systems.

Why Use External ID?
Emails may change, but the External ID remains constant. Using External IDs helps prevent duplicate accounts when students use multiple email addresses.

💡 Recommendations:

Always store the External ID (e.g., Canvas User ID) in your CRM.
If a student is already added to Canvas, use their externalId when inviting them to a degree.
If the student hasn’t been added to Canvas, use their email.
The externalId cannot be changed or deleted via the API.

Important Note: Account merging is not available in Woolf. Carefully handle External IDs to avoid errors.

2. Required and Optional API Fields

Field	Required	Description
`degreeId`	Yes	Identifies the degree to which the student will be invited.
`email`	Yes	Used to invite the student if the `externalId` is not provided.
`externalId`	Optional	Unique identifier (e.g., Canvas User ID). Recommended to avoid account duplication.
`tuitionCost`	Optional	Overrides the default tuition cost for the degree.
`currency`	Optional	Specifies the currency for tuition cost. If not provided, the default currency set for the degree is used.
`nameFirst`	Optional	First name of the student.
`nameLast`	Optional	Last name of the student.

Example Request

🚀 Request (Try It)

Example Response


{
  "data": {
    "addStudentToDegree": {
      "id": "1cb91e3f-2eab-4c8d-902f-944c86937dfc"
    }
  }
}

Invitation Logic

The API handles student invitations as follows:

If externalId exists:
The system invites the user associated with the externalId to the degree. Any email provided in the request is ignored.
If externalId does not exist but email exists:
The system invites the user associated with the email to the degree.
If neither externalId nor email exists:
The system creates a new user and invites them to the degree.

Common Scenarios and Best Practices

Inviting Students Using External IDs

Use the externalId when the student already exists in Canvas or another integrated LMS.
This prevents duplicate records and ensures accurate syncing of student data.

Specifying Tuition Costs and Currency

Override the default tuition cost for specific students by passing tuitionCost and currency values.
If no values are provided, Woolf will apply the default tuition cost and currency set for the degree.

Handling Missing Information

If externalId or email is missing, ensure the necessary data is collected before making the API request.
Always verify the degreeId from Woolf AMS to avoid errors.

FAQs

Can I invite students using only their email addresses?

Yes. If a student has not been added to Canvas or another LMS, you can invite them using their email.

What happens if I provide both externalId and email?

The system prioritizes externalId and ignores the email provided.

Can I update the externalId for a student?

No. The externalId is immutable once assigned.

What if a student is already enrolled in a degree?

If the student is already enrolled in the specified degree, the API will not duplicate their enrollment.

How do I fetch the degreeId?

You can use the the College query in the Woolf API or retrieve it from the AMS UI under Degree Details.