Jostle's User Provisioning API helps your company manage user accounts automatically, saving time and effort and ensuring that your users are up to date. User Provisioning API features include the ability to create, read, update (including disable) and delete users in Jostle.
Jostle's API documentation page can be found here.
In order to use Jostle's API, you will need an API key. This can be obtained by a System Admin in Admin Settings > User Data To/From Other Systems > Manage User Provisioning (if you do not see "Manage User Provisioning" here, contact Support to have this page enabled in your Admin Settings).
SCIM API
Jostle's User Provisioning API is based on the System for Cross-domain Identity Management (SCIM) 2.0 standard.
The content-type for POST, PUT and PATCH operations should be: application/scim+json.
Caller should specify in the Accept header that it accepts application/json.
API Calls
The following API calls from the SCIM standard are supported:
OPERATION |
PATH |
HTTP METHOD |
DESCRIPTION |
| Get Service Provider Configuration | /ServiceProviderConfig | GET | Metadata service that returns information on details about what part of SCIM is support by our API. |
| Get Resource Types | /ResourceTypes | GET | Metadata service that returns resource type information for resources that are supported by our API. We only support User and not Group. |
| Get Resource Type for | /ResourceTypes/User | GET | Metadata service that returns resource type information for User. |
| Get Schemas | /Schemas | GET | Metadata service that returns schema information for schemas that are supported by our API. We support the SCIM Core User schema and our own User extension schema. |
| Get Schema for SCIM Core User Type |
/Schemas/urn:ietf: params:scim:schemas: core:2.0:User |
GET | Metadata service that returns schema information for SCIM Core User schema that we support. We currently support a limited number of fields, as shown below. |
| Get Schema for Jostle User Type Extension |
/Schemas/urn:ietf: params:scim:schemas: extension:jostle: 2.0:User |
GET | Metadata service that returns schema information for our User schema extension. Refer to the supported fields shown below. |
| Get User by Id | /Users/{id} | GET | Get User for specified id. The id in our case is the id of the User in login server |
| Get Users with GET | /Users | GET | Get Users. We don’t support sorting. The only filtering we support is on username with equality operation. We support paging when filtering is not specified. |
| Get Users with POST | /Users/.search | POST | Get Users. We don’t support sorting. The only filtering we support is on username with equality operation. We support paging when filtering is not specified. |
| Create User | /Users | POST | Create a User |
| Delete User | /Users/{id} | DELETE | Delete a User |
| Update User with PUT | /Users/{id} | PUT | Update User with PUT. This requires that ALL information about the User has to be provided as part of the PUT as all of the User gets updated. |
| Update User with PATCH | /Users/{id} | PATCH | Update User with PATCH. This allows for updating only the specified fields of a User. The operations supported for fields are “add”, “replace”, and “remove”. |
| Bulk Operation | /Bulk | POST | Allows for multiple operations to be supported in one request. There can be mixed operations in one request. There is a limit of 50 items per request and a total request size limit of 20MB. |
| Get on Self | /Me | GET | Get information on the User who owns the key which is used for the request. |
| Delete Self | /Me | DELETE | Delete the User who owns the key which is used for the request. |
| Update Self with PUT | /Me | PUT | Update the entire User who owns the key which is used for the request. |
| Update Self with PATCH | /Me | PATCH | Update the specified fields in User who owns the key which is used for the request. |
User Resource
Listed below are details on the supported User Provisioning API fields and how they map to Jostle (Note: at this time, not all of these fields are available through MS Entra ID User Provisioning).
| API | Jostle |
| username | Username |
| active |
UserStatus (Active/Disabled/Suspended)* *Disabled/Suspended controlled by API preference in Admin Settings |
| name.familyName | LastName |
| name.givenName | FirstName |
| nickname | Nickname |
| emails (type) | Work, Personal, Alternate1, Alternate2 |
| emails (value) | (email address) |
| emails (primary) | (note - only one primary) |
| phoneNumbers (type) | WorkOfficePhone, WorkMobilePhone, HomePhone, PersonalMobilePhone |
| phoneNumbers (value) | (phone number) |
| phoneNumbers (primary) | (note - only one primary) |
| addresses (type) | Address1, Address2 |
| addresses (streetaddress) | Street |
| addresses (locality) | City |
| addresses (region) | State |
| addresses (postalcode) | Zip |
| addresses (country) | Country |
| employeeID | EmployeeID |
| alternateEmail1Label | AlternateEmail1Label |
| alternateEmail2Label | AlternateEmail2Label |
| joinDate | Joined |
| birthDate | BirthDate |
| jobCategory | JobCategory |
| customBadge | Program Level (re: User Badges) |
| customProfile | CustomProfileCategory |
| locations (pre-existing only) | Locations |
| customLabels (address labels) | MessagingAddressLabel1, MessagingAddressLabel2, MessagingAddressLabel3 |
| customProfileField | CustomProfileFieldLabel, CustomProfileFieldValue |
| loginType | InviteForAuthenticationMethod (Jostle, Google, SSO) |
| userState (read-only field, depending on provisioning settings, may indicate if user is Disabled or Suspended) | N/A |
| customFilterCategory | CustomFilterCategory |
0 Comments