Skip to content

User Import CSV Format

This guide details the CSV format for importing student user data into Arbol.

Template Download

Download the user import template: user_import_template.csv

Required Fields

These fields must be present in every user import:

Field Name Type Description Example
Student ID String Unique student identifier S123456789
Email String Student email address (must be unique) john.doe@university.edu
First Name String Student's first name John
Last Name String Student's last name Doe

Optional Fields

Include these fields to enhance student profiles:

Field Name Type Description Example
SSO Identifier String Unique SSO identifier for authentication jdoe123 or john.doe@university.edu
Mobile Number String Phone number (10 or 11 digits) 555-123-4567
Bypass Term Import Boolean Use Arbol's standard term definitions true, false, yes, no, 1, 0
License Start Date Access start date 2024-01-15 or 01/15/2024
License End Date Access end date 2024-05-15 or 05/15/2024

SSO Identifier Usage

The SSO Identifier field is used when Single Sign-On (SSO) is configured for your institution. This identifier must match the SAML NameID (the value in the <saml:NameID> element) sent by your Identity Provider in the SAML assertion.

Behavior depending on what you provide:

  • SSO Identifier provided: The user is "bound" immediately — only an exact NameID match from your IdP will authenticate them via SSO.
  • SSO Identifier left blank: The user can authenticate via SSO using email-based fallback matching. On their first successful SSO login, Arbol will automatically populate SSO Identifier with the exact NameID value the IdP sent (case preserved). After that, the user is bound — only exact NameID matches will authenticate them.

Updating SSO Identifier after a user is bound: Re-uploading a user import file with a populated SSO Identifier column will update the value for existing users. This is the recommended way to update bindings if your IdP's NameID source changes (e.g., you switched from email to a UUID format). Once a user is bound, their SSO Identifier is not updated automatically by the SSO login flow — administrator action via user import (or ActiveAdmin for one-off changes) is required.

Bypass Term Import Explained

What it controls: Whether this student uses Arbol's standard academic term definitions or waits for your institution to provide term data via School Bill imports.

  • true (Bypass enabled): Student uses Arbol's predefined standard academic terms (Fall, Spring, Summer). Financial plans become available immediately based on Arbol's term schedule.
  • false (Default): Student's financial planning options depend on your institution providing term data through School Bill imports. Plans only become available after you import billing data for specific terms.

When to use true: - You don't plan to import school bill data for this student - You want students to access planning tools immediately without waiting for billing data imports - The student is in a special program not following your institution's standard billing cycle

When to use false (or leave blank): - You will be importing school bill data for this student - You want term availability to match your institution's actual billing terms

Data Formats

Boolean Values

Accepted values for boolean fields:

  • True: true, t, yes, y, 1
  • False: false, f, no, n, 0

Date Formats

The system accepts multiple date formats:

  • YYYY-MM-DD (preferred)
  • MM/DD/YYYY
  • MM/DD/YY
  • DD-MMM-YY

Phone Numbers

  • Must include area code
  • Country code optional (1 for US)
  • Accepts formats with spaces, dashes, parentheses
  • Examples: 555-123-4567, (555) 123-4567, 1-555-123-4567

Sample CSV

Student ID,Email,First Name,Last Name,SSO Identifier,Mobile Number,Bypass Term Import,License Start,License End
S123456789,john.doe@university.edu,John,Doe,jdoe,555-123-4567,false,2024-01-15,2024-05-15
S987654321,jane.smith@university.edu,Jane,Smith,jsmith,(555) 987-6543,false,2024-01-15,2024-05-15
S456789123,mike.johnson@university.edu,Michael,Johnson,,,true,2024-01-15,2024-12-31

Import Behavior

  • Import processes rows sequentially
  • Invalid rows are skipped but don't stop the import ()

  • Large files (1000+ records) may take several minutes, even longer to send notifications due to carrier limitations

  • Note: Only US based phone numbers supported at the moment.

Notification Control

  • Manual uploads: Notification settings can be configured individually for each upload
  • SFTP imports: Notification settings are saved with the SFTP configuration and apply to all automated imports

New Students

When a student doesn't exist:

  1. Creates new user account
  2. Sends an onboarding email if notifications are enabled for this import:
    • SSO Identifier provided — sends the SSO welcome email pointing the student at your SSO sign-in. There is no activation link; their first SSO sign-in is the verification event.
    • SSO Identifier blank — sends the set-password activation email. The student clicks the link, sets a password, and is verified at that point.
  3. SMS consent prompt fires alongside the welcome if the student has a mobile number, is not already subscribed to SMS alerts, and has notifications enabled.

Existing Students

When a student already exists (matched by email or student ID):

  1. Updates provided fields
  2. Preserves existing data for blank fields
  3. Cannot change student ID once set
  4. Cannot transfer students between schools

Re-engagement Rules

These rules govern whether an existing row triggers another welcome email on re-import:

Student state Re-import with notifications on
SSO Identifier set, has not completed an SSO sign-in Re-sends the SSO welcome email and refreshes the engagement timestamp
SSO Identifier set, has completed an SSO sign-in No welcome is re-sent — the student is already verified
SSO Identifier blank, has not set a password Re-sends the set-password activation link (existing behavior)
SSO Identifier blank, has set a password No re-send — the activation link is already cleared

The first successful SSO sign-in is the verification event for SSO users (equivalent to the student clicking the set-password link in the non-SSO flow). Once verified, re-imports do not re-trigger the welcome. See Welcome Email Timing on the Authentication page for the full lifecycle.

Validation Rules

Required Field Validation

  • Student ID and Email cannot be empty
  • First Name and Last Name are required
  • Email must be valid format (contains @ and domain)

Data Quality Checks

  • Dates validated for logical values
  • Boolean fields checked for valid values
  • Leading/trailing whitespace automatically trimmed

Note: Cannot change student ID for existing users

Error Handling

Error Response Format

Errors are reported by row number with specific messages:

Row 2: john.doe@university.edu
- 'Mobile Number': '555-1234' must include area code
- 'License Start' must be a valid date value

Row 5: jane.smith@university.edu
- Email exists on a user at another school

Warning Messages

Non-critical issues that don't prevent import:

  • Invalid phone number format (record imports without phone)
  • Future license dates (accepted but noted)

Getting Support for Data Import Issues

Contact Arbol support at support@growarbol.com for help with data import issues.

When contacting support about data management issues, include:

  • Import ID (found under "View Details" in the import history table)
  • Description of the issue or error message
  • Whether this is a manual upload or FTP import
  • Screenshot of any error messages (if available)