Interfolio — Provision Users and Product Access via the API

Provision Users and Product Access via the API

As an integrations client with Interfolio, you can provision users and manage their access to our products through our API. This document will cover how to create and update users, and how to subscribe them to our products. In order to do these things, you will need an API profile provisioned by Interfolio with API keys and user provisioning permissions.

For clients using our unique identifier (UID) feature, Interfolio now has a dedicated data field intended to capture a consistent, unique identifier value for every user in all Interfolio Faculty Information System modules, including Faculty Search, Lifecycle Management, and Review, Promotion & Tenure. Rather than depending upon email addresses, or any Interfolio-generated IDs*, this field is meant to reflect whatever permanent, unique identifier your institution already uses to keep track of each individual employee.

UID is available for opt-in today in all of our products.

Please note that clients using the API for bulk user creation will need to update to the V2 Bulk Users Endpoint to support UID and User Type.

For testing purposes, the best practice is to create a small group (<5) of fake profiles with dummy data and fake email addresses. A user's core profile contains their name, address, phone number, and email address, and changes to user profiles in a development tenant will be reflected in that user's profile in any other tenant to which they're related (e.g., production or another institution) and vice versa.

See this article for more on Interfolio's environment architecture.

User Provisioning via the API

Provision User

When creating a user, the basic user information parameters are required. You have the option to specify a proprietary ID as “institution_user_id” that you can use to look up the user individually. You also have the option to provision a user with an ID to use with one of the available Single Sign On (SSO) strategies. The API responds with the user object and its given attributes. The attribute that we use to track users across our system is PID (Personal Identification.) This is an Interfolio assigned identifier used across our entire Faculty Information System suite of software. It is needed for those few endpoints that assist in managing the linkages across the software suite. The PID for a faculty member is retrievable through the API using the /users/{userid} endpoint with the data=detailed parameter. That attribute is what you will use to update users, grant product access to users, and revoke access to the system.

Please note that institution_user_id is required for creating a user for tenants with UID (unique identifier) enabled. and optional for tenants without UID.

Method	Domain	Endpoint
POST	https://iam-api.interfolio.com	/iam/{tenant_id}/users

Parameter	Type	Format	Required?
Authorization	String	HEADER	✔
TimeStamp	String	HEADER	✔
tenant_id	Integer	URL	✔
first_name	String	POST	✔
last_name	String	POST	✔
email	String	POST	✔ (required for tenants with UID, and optional for tenants without UID)
institution_user_id	String	POST	✔ (required for tenants with UID, and optional for tenants without UID)
saml_id	String	POST	X
user_type	String	POST	X ("internal" or “external”)

Update User

When updating a user, the user’s unique “pid” is required. The API updates the core user record, and a successful response has no content.

Method	Domain	Endpoint
PUT	https://iam-api.interfolio.com	/iam/{tenant_id}/users/{pid}

Parameter	Type	Format	Required?
Authorization	String	HEADER	✔
TimeStamp	String	HEADER	✔
tenant_id	Integer	URL	✔
pid	Integer	URL	✔
first_name	String	PUT	X
last_name	String	PUT	X
email	String	PUT	X
saml_id	String	PUT	X
user_type	String	POST	X ("internal" or “external”)

View User

You can look up and view a given user with their “pid”, “email”, or “institution_user_id” based on the endpoint that you use. If you wish to look up a user by “institution_user_id”, they must have a valid value for that attribute. The API will respond with the user object.

Method	Endpoint
GET	/iam/{tenant_id}/users/pid/{pid}
GET	/iam/{tenant_id}/users/email/{email}
GET	/iam/{tenant_id}/users/institution_user_id/{institution_user_id}

Parameter	Type	Format	Required?
Authorization	String	HEADER	✔
TimeStamp	String	HEADER	✔
tenant_id	Integer	URL	✔
pid	Integer	URL	✔*
email	String	URL	✔*
institution_user_id	String	URL	✔*

* Indicates required for the relevant endpoint, but not for each endpoint. For instance, the "email" parameter would only be required for a GET to the lookup endpoint for retrieving a user by email.

Product Access via the API

Manage Product Access

For Faculty180, the user attribute “institution_user_id” is the user’s Faculty ID and is required. The parameter “sendemail” is a boolean where the “true” value will send the user an email message when they are added to Faculty180 and passing “false” or not passing the parameter altogether will not send the user an email. Granting a user access to the Faculty180 product through this endpoint creates a user record in your FAR database and gives them default permissions. You will still need to configure product-level permissions. The API will respond with a successful response and no content.

Method	Domain	Endpoint
POST	https://faculty180.interfolio.com	/fars/{tenant_id}/users/{pid}/subscribe

Parameter	Type	Format	Required?
Authorization	String	HEADER	✔
TimeStamp	String	HEADER	✔
INTF-DatabaseID	String	HEADER	✔
tenant_id	Integer	URL	✔
pid	Integer	URL	✔
institution_user_id	String	POST	✔
facultyid	String	POST	✔
sendemail	Boolean	POST	X
employmentstatus	String	POST	X
primaryunit	Integer	POST	X
rankname	String	POST	X
accounttype	String	POST	X
suffix	String	POST	X
officebuilding	String	POST	X
officenumber	String	POST	X
phone	String	POST	X
gender	String	POST	X
race	String	POST	X
nationality	String	POST	X
homephone	String	POST	X
teachinginterest	String	POST	X
researchinterest	String	POST	X
biography	String	POST	X

Parameter	Type	Format	Required?
homestreet1	String	POST	X
homestreet2	String	POST	X
homecity	String	POST	X
homestate	String	POST	X
homezipcode	String	POST	X
homecountry	String	POST	X
cellphone	String	POST	X
emergencycontact	String	POST	X
emergencycontactphone	String	POST	X
pager	String	POST	X
personalstreet1	String	POST	X
personalstreet2	String	POST	X
personalcity	String	POST	X
personalstate	String	POST	X
personalzip	String	POST	X
languages	String	POST	X

Remove Access to Faculty180

Removing a user from the Faculty180 product will remove their institution user's record from your user list and remove their permissions to access the product. The API will return a success response.

Method	Domain	Endpoint
PUT	https://faculty180.interfolio.com	/fars/{tenant_id}/users/{pid}/unsubscribe

Grant Access to Review, Promotion, and Tenure

Granting a user access to the Review, Promotion, and Tenure product through this endpoint creates an institution user record in your tenant hierarchy and gives them the default permissions. You will still need to configure product level permissions. The API will respond with a success response and the information for the user who was added.

Method	Domain	Endpoint
POST	https://logic.interfolio.com	/byc-tenure/{tenant_id}/users/{pid}/subscribe

Parameter	Type	Format	Required?
Authorization	String	HEADER	✔
TimeStamp	String	HEADER	✔
tenant_id	Integer	URL	✔
pid	Integer	URL	✔

Remove Access to Review, Promotion, and Tenure

Removing a user from the Review, Promotion, and Tenure will remove their institution users record from your tenant hierarchy and remove their permissions to access the product. The API will return a success response and the information of the user who was removed.

Method	Domain	Endpoint
PUT	https://logic.interfolio.com	/byc-tenure/{tenant_id}/users/{pid}/unsubscribe

Grant Access to Faculty Search

Granting a user access to the Faculty Search product through this endpoint creates an institution user record in your tenant hierarchy and gives them the default permissions. You will still need to configure product-level permissions. The API will respond with a success response and the information for the user who was added.

Method	Domain	Endpoint
POST	https://logic.interfolio.com	/byc-search/{tenant_id}/users/{pid}/subscribe

Parameter	Type	Format	Required?
Authorization	String	HEADER	✔
TimeStamp	String	HEADER	✔
tenant_id	Integer	URL	✔
pid	Integer	URL	✔

Remove Access to Faculty Search

Removing a user from the Faculty Search will remove their institution user's record from your tenant hierarchy and remove their permissions to access the product. The API will return a successful response and the information of the user who was removed.

Method	Domain	Endpoint
PUT	https://logic.interfolio.com	/byc-search/{tenant_id}/users/{pid}/unsubscribe

How Can We Help?

Search Results

Refine by Product