Check out our upcoming webinars and client office hours calendar here!

How Can We Help?

Search icon

Search Results

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
 
Was this article helpful?
Give feedback about this article