API: enrollSubscriptionVariants
  • 3 Minutes to read
  • Dark
    Light

API: enrollSubscriptionVariants

  • Dark
    Light

Article summary

  • Starting June 1, 2022, SmarterU will require all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
  • If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
  • Tags are required unless specified.

Description

The enrollSubscriptionVariants method enrolls users in subscription variants that you have available. 

Who Has Access

The following users have access to the enrollSubscriptionVariants method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>enrollSubscriptionVariants</Method>
   <Parameters>
      <SubscriptionVariantEnrollment>
         <Enrollment>
            <User>
               <Email><![CDATA[]]></Email>
                  - OR - 
               <EmployeeID><![CDATA[]]></EmployeeID>
            </User>
            <GroupName><![CDATA[]]></GroupName>
            <SubscriptionVariantID><![CDATA[]]></SubscriptionVariantID>
            <EnrollmentTag><![CDATA[]]></EnrollmentTag>
         </Enrollment>
      </SubscriptionVariantEnrollment>
   </Parameters>
</SmarterU>    

SubscriptionVariantEnrollment Tag Group

The SubscriptionVariantEnrollment tag group is a container for the subscription enrollments.

<SubscriptionVariantEnrollment>
   <Enrollment>
      <User>
         <Email><![CDATA[]]></Email>
            - OR - 
         <EmployeeID><![CDATA[]]></EmployeeID>
      </User>
      <GroupName><![CDATA[]]></GroupName>
      <SubscriptionVariantID><![CDATA[]]></SubscriptionVariantID>
      <EnrollmentTag><![CDATA[]]></EnrollmentTag>
   </Enrollment>
</SubscriptionVariantEnrollment>

The SubscriptionVariantEnrollment tag may contain the following.

Enrollment

A container for the subscription enrollment. Refer to Enrollment Tag Group.

Enrollment Tag Group

The Enrollment tag group is a container for a subscription enrollment. 

<Enrollment>
  <User>
     <Email><![CDATA[]]></Email>
        - OR -
     <EmployeeID><![CDATA[]]></EmployeeID>
  </User>
  <GroupName><![CDATA[]]></GroupName>
  <SubscriptionVariantID><![CDATA[]]></SubscriptionVariantID>
  <EnrollmentTag><![CDATA[]]></EnrollmentTag>
</Enrollment>

Each subscription enrollment is contained in an Enrollment tag and may contain the following. 

The enrollSubscriptionVariants method supports up to enrollments per call. 

User

The user to enroll in a subscription variant. The User tag contains one of the following.

TagDescription

Email

The user's mail address. This tag is mutually exclusive with the EmployeeID tag. This is the Email returned by the getUser and listUsers methods.

EmployeeID

The user's employee ID. This tag is mutually exclusive with the Email tag. This is the EmployeeID returned by the getUser and listUsers methods.

GroupName

The enrollment group's name. This is the Name returned by the getGroup and listGroups methods.

  • The user you are trying to enroll in a subscription variant must already be assigned to this group.
  • The subscription must already be assigned to this group. 

SubscriptionVariantID

The subscription variant's system-generated identifier. This is the VariantID returned by the listVariants method. 

EnrollmentTag (optional)

The enrollment tag.

API Response XML Package

The API response XML package will always include a Result, Info, and Errors tag.

<SmarterU>
   <Result></Result>
   <Info>
      <Enrollments>
         <Enrollment>
            <User><![CDATA[]]></User>
            <SubscriptionVariantID><![CDATA[]]></SubscriptionVariantID>
         </Enrollment>                                           
     </Enrollments>
   </Info>   

   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

The Enrollments tag is a container for the subscription enrollments processed by the enrollSubscriptionVariants method. Each subscription enrollment is contained in an Enrollment tag and may contain the following.

User

The user's identifier. This returns the same value that was provided in the Enrollment tag group.

SubscriptionVariantID

The subscription variant's system-generated identifier. This returns the same value that was provided in the Enrollment tag group.

Because this method can be used to perform multiple enrollments, be sure to check the Errors tag for error codes. It's possible for the Result tag to return Success even when errors are returned.

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>
   <Info>
      <Enrollments>
         <Enrollment block="1">
            <User><![CDATA[dana.brown@finashoes.com]]></User>
            <SubscriptionVariantID>16</SubscriptionVariantID>
         </Enrollment>
      </Enrollments>
   </Info>

   <Errors>
   </Errors>
</SmarterU> 

Error Codes

Error CodeMessage
ESV:01
The E-mail address provided is not valid.
ESV:02
The Employee ID provided is not valid.
ESV:03
The Group Name provided is not valid.
ESV:04
The Subscription Variant ID provided is not valid.
ESV:05
The Enrollment Tag provided is not valid.
ESV:06
The required permissions are not met to call the enrollSubscriptionVariants method.
ESV:07
Enrollment %blocknum% - The email address '%emailaddress%' is not a valid user.
ESV:08
Enrollment %blocknum% - The employee id '%employeeid%' is not a valid user.
ESV:09
Enrollment %blocknum% - No user identifier was provided.
ESV:10
Enrollment %blocknum% - The Subscription Variant ID provided is not valid.
ESV:11
Enrollment %blocknum% - The group name '%groupname%' is not valid.
ESV:12
Enrollment %blocknum% - You cannot assign the subscription variant under the group selected.
ESV:13
Enrollment %blocknum% - You do not have permissions to assign a user a subscription variant under the group selected.
ESV:14
Enrollment %blocknum% - %enrollmenterror%
This is a dynamic error in the enrollment process. Reasons may include:
  • Insufficient credits if credits are required for enrollment
  • User already has an unlimited enrollment in the subscription
  • The subscription variant has expired

Was this article helpful?