CSV Imports

CSV File Formats

General Guidelines

  • All CSV files must contain a header row.
  • The header row must contain all required fields.
  • Optional fields may be omitted from the header.
  • Header order does not matter.
  • Fields that contain a comma must be double-quoted. Example: Philosophy, Art, and Poetry should appear in the CSV as "Philosophy, Art, and Poetry"
  • Fields that contain double-quotes (") must be double-quoted and escaped. To escape double quotes in a field you use another double-quote. For example, if you want a field in Pronto to appear as Calculus "Lite" then it should appear in the CSV as "Calculus ""Lite"""

Supported file encodings: UTF-8, UTF-16

Identifiers

Users, groups, and categories each have two unique identifiers. The first is the Pronto ID which is a number assigned internally by Pronto when a record is first created. (examples: user_id, category_id, group_id)

The second is an External ID which you can use to store the identifier of a corresponding record in your external system. This identifier can be used however you like, but it must be unique within your organization.

To update or add an External ID to an existing record, specify both identifiers. Pronto will lookup the record using the Pronto ID and update that matching record's External ID. To remove the External ID, include the external_id column header, but leave the value blank.

How existing records are matched

Pronto only ever looks up an existing record by its Pronto ID or its External ID. Other fields, such as a user's email or phone, are never used to find an existing record. This means:

  • A row with a Pronto ID is always an update. If no record in your organization has that Pronto ID, the row is rejected.
  • A row with an External ID but no Pronto ID is an update if a record in your organization already has that External ID. Otherwise it is treated as a new record.
  • A row with neither identifier is always treated as a new record.
  • A row with an External ID that does not exist yet and an email (or phone) that already belongs to a user results in an import error, not an update. The existing user is not matched by email, so the row is treated as a new user and rejected as a duplicate.

When a row is treated as a new record but a matching record already exists (for example, a user with the same email address), the row is rejected as a duplicate and nothing is changed. See the notes under each file type for details.

Users

File Name: users.csv

Field Type Required Max Length Default Description
user_id integer no* The internal Pronto ID.
external_id string no* 255 A customer-supplied unique user identifier. This must be unique within your organization.
first_name string yes 60 The user's given name. Note that in the Pronto app, the full name is always shown so if your system only has a full name, you can arbitrarily split it.
last_name string yes 60 The user's surname.
title string no 40 The user's title. This field will only be imported if the feature is enabled for the organization.
pronouns string no 40 The user's preferred pronouns. This field will only be imported if the feature is enabled for the organization.
phone string no^ 15 The user's phone number in E.164 format (e.g. +18012345678).

Alternatively, if all phones in the CSV are within a single country, you can specify a default country code when creating an import batch and use local phone number formatting in this field.
email string no^ 100 The user's email address
role enum no user The user's role.
Values: user, manager, admin
status enum no active The status of the user in the org. You can deactivate or reactivate a user by setting this status.
Values: active, deactivated

*When updating or deactivating or re-activating a user, one is required: user_id, external_id


^When creating a new user at least one is required: email, phone

Additional Notes

  • When creating a new user you must not specify user_id. Pronto will create this internally upon record creation.
  • When creating a new user you may specify external_id. You can then reference this user in other files or subsequent batches.
  • If you specify both user_id and external_id, user_id will be used for lookup and the external_id will be updated to the specified value.
  • Existing users are matched only by user_id or external_id, never by email or phone. If a row has no user_id and its external_id does not match any user in your organization (for example, the user was created without one), Pronto treats the row as a new user. Because the email or phone already belongs to an existing user, the row is rejected with Email address is already in use by another user. (or the phone equivalent) and the existing user is not updated.
  • To start using external IDs for users that currently exist in Pronto without one, run a batch that includes both user_id and external_id for each user. Pronto finds the user by user_id and saves the external_id. From then on, external_id alone is enough to update those users. You can find each user's user_id in Org Management or via the Pronto API.
  • If your import batch is configured to automatically deactivate users that are not present in users.csv, be aware that a rejected row does not count as "present". An existing user whose row was rejected for a duplicate email or phone may be deactivated by that batch.

Examples

Creating new users. One record has an email AND a phone, while the other just an email:

first_name,last_name,email,phone
Mookie,Betts,mookie@dodgers.c,+12133456789
Freddie,Freeman,freddie@dodgers.com,

Creating new users with external IDs:

external_id,first_name,last_name,email
MYSYSTEM_ID_100,Mookie,Betts,mookie@dodgers.com
MYSYSTEM_ID_200,Freddie,Freeman,freddie@dodgers.com

Updating roles for existing users using their Pronto IDs:

user_id,first_name,last_name,email,role
23723382,Mookie,Betts,mookie@dodgers.com,admin
23947276,Freddie,Freeman,freddie@dodgers.com,user

Deactivating users using their external IDs:

external_id,first_name,last_name,email,status
MYSYSTEM_ID_100,Mookie,Betts,mookie@dodgers.com,deactivated
MYSYSTEM_ID_200,Freddie,Freeman,freddie@dodgers.com,deactivated

Assigning external IDs to existing users that were created without one. The users are found by user_id and their external_id is saved so future batches can reference them by external_id alone:

user_id,external_id,first_name,last_name,email
23723382,MYSYSTEM_ID_100,Mookie,Betts,mookie@dodgers.com
23947276,MYSYSTEM_ID_200,Freddie,Freeman,freddie@dodgers.com

Suppose Mookie and Freddie already exist in Pronto but were created without external IDs. This batch will not update them. Because there is no user_id and no existing user has these external IDs, each row is treated as a new user and rejected with Email address is already in use by another user.:

external_id,first_name,last_name,email
MYSYSTEM_ID_100,Mookie,Betts,mookie@dodgers.com
MYSYSTEM_ID_200,Freddie,Freeman,freddie@dodgers.com

Categories

File Name: categories.csv

Field Type Required Max Length Default Description
category_id integer no* The internal Pronto ID.
external_id string no* 255 A customer-supplied unique user identifier.
title string yes 255 user The title of the category.
status enum no active The status of the caetegory. You can delete a record using this status.
Values: active, deleted

*When updating or deleting a category, one is required: category_id, external_id

Examples

Creating new categories without external IDs.

title
Math 100
English 440

Creating new categories with external IDs:

external_id,title
MYSYSTEM_ID_100,Math 100
MYSYSTEM_ID_200,English 440

Deleting categories using external IDs:

external_id,title,status
MYSYSTEM_ID_100,Math 100,deleted
MYSYSTEM_ID_200,English 440,deleted

Groups

File Name: groups.csv

Field Type Required Max Length Default Description
group_id integer no* The internal Pronto ID.
external_id string no* 255 A customer-supplied unique user identifier.
category_id integer no The group's category using the category's internal Pronto ID.
category_external_id string no 255 The groups category using the category's external ID.
title string yes 100 The title of the group.
status enum no active The status of the group. You can delete a record using this status.
Values: active, deleted

*When updating or deleting a group, one is required: group_id, external_id

Memberships

File Name: memberships.csv

Field Type Required Max Length Default Description
group_id integer no* The group's internal Pronto ID.
group_external_id string no* 255 The group's customer-supplied unique user identifier.
user_id integer no* The user's internal Pronto ID.
user_external_id string no* 255 The user's customer-supplied unique user identifier.
user_phone string no* 15 The user's phone number in E.164 format (e.g. +18012345678) or in the import batch's default country formatting style (if specified).
user_email string no* 100 The user's email address.
role enum no member The user's group role.
Values: member, owner
status enum no active The status of the user in the org. You can remove someone from a group using this status.
Values: active, deleted

*A membership record ties a user to a group, so an identifier must be specified for each:

  • For user, one is required: user_id, user_external_id, user_email, user_phone
  • For group, one is required: group_id, group_external_id
Previous
Overview
Next
Introduction