Articles in this section

How do I integrate user management?

Avatar
Travis Truett
  • Updated
Follow

User Provisioning API

The User Provisioning API is being phased out in Fall/Winter 2020.

If you'd like to pursue programmatically updating, creating, and deactivating users learn more about Ambition's User API Integration here.

The User Provisioning API can be used to automatically sync Users and Groups from an existing system to Ambition.

What fields are supported?

Users:

Groups:

 

Example File Exported from HRM System

first_name last_name email role team_name
Jason Smith jason@yourcompany.com Account Executive  Dogs
 Susan Simpson  susan@yourcompany.com Customer Support Cats

 

 

All Supported Fields

View all supported fields:

  • By utilizing the URL setup seen below.

https://<SUBDOMAIN>.ambition.com/docs/#!/account/Public_Api_Account_Create

Ensure you replace SUBDOMAIN with your Ambition instance subdomain.

  • Within any API integration in Ambition, click the API Sandbox option.
    ↳ No API integrations or unsure how to access an API Integration? Learn more here.

Screen_Shot_2020-09-28_at_3.50.01_PM.png

 

Users

Create / Update User

Given the example file above, you will need to append username and is_active and optionally remove group membership fields.

is_active first_name last_name email username
true  Jason Smith jason@yourcompany.com jason@yourcompany.com
 true  Susan Simpson  susan@yourcompany.com susan@yourcompany.com

 

API Details

Endpoint: https://SUBDOMAIN.ambition.com/api/v1/account/
HTTP Request Verb: POST
Authorization Header: Authorization: Token API_TOKEN (Utilize a token from an existing API integration within Ambition or enable new API integration)
Content Type Header: Content-Type: CONTENT_TYPE

CONTENT_TYPE Contents
application/json JSON Formatted Data
text/csv CSV Formatted Data

 

Example

cURL - JSON 

curl \
-H "Authorization: Token AUTH_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
--data-binary "@/path/to/account-membership.json" \
https://SUBDOMAIN.ambition.com/api/v1/account/

cURL - CSV

curl \
-H "Authorization: Token AUTH_TOKEN" \
-H "Content-Type: text/csv" \
-X POST \
--data-binary "@/path/to/account-membership.csv" \
https://SUBDOMAIN.ambition.com/api/v1/account/

 

View of the Account POST options via the API Sandbox within Ambition.

Screen_Shot_2020-09-28_at_4.08.12_PM.png

 

 

Deactivate User

In order to deactivate a user you will set the is_active field to false.

You can create and deactivate users with a single request

 

 

Groups

Create Group Type and Groups / Assign Group Membership

Ambition's hierarchy is composed of Group Types and Groups.

Group Type: Generic level of hierarchy... for example Region, Office, Team.
Group: Specific entity within a Group Type... for example Northeast, Boston, Dogs.

An Account can only belong to one Group per Group Type

The API can automatically create Group Types, Groups, and set Group Memberships OR you can create your Group Types and Groups hierarchy within the product, and then use the API to set Group memberships.

 

Three separate POST requests will be needed for the above scenario:

1. Create Group Type via POST to /group_type.

Screen_Shot_2020-09-28_at_4.20.31_PM.png

2. Create Group via POST to /group.

Screen_Shot_2020-09-28_at_4.20.50_PM.png

3. Add exiting Users to Group via POST to /group_membership.

Screen_Shot_2020-09-28_at_4.21.02_PM.png

 

If using the API to set memberships for pre-existing Groups you must exactly match the Group names within Ambition. This includes case sensitivity and whitespace.

Given the example file above, you will need to flatten group columns into individual rows that reference the account's username.

username group_type group_name
jason@yourcompany.com Role Account Executive
jason@yourcompany.com Team Dogs
susan@yourcompany.com  Role  Customer Support
 susan@yourcompany.com  Team  Cats

 

API Details

Endpoint: https://SUBDOMAIN.ambition.com/api/v1/group_membership/
HTTP Request Verb: POST
Authorization Header: Authorization: Token API_TOKEN (Utilize a token from an existing API integration within Ambition or enable new API integration)
Content Type Header: Content-Type: CONTENT_TYPE

CONTENT_TYPE Contents
application/json JSON Formatted Data
text/csv CSV Formatted Data

  

Example

cURL

curl \
-H "Authorization: Token AUTH_TOKEN" \
-H "Content-Type: CONTENT_TYPE" \
-X POST \
-d '[{"username": "jason@yourcompany.com", "Role": "Account Executive"}]' \
https://SUBDOMAIN.ambition.com/api/v1/group_membership/

 

View of the Group Membership POST via the API Sandbox within Ambition.

Screen_Shot_2020-09-28_at_4.07.24_PM.png 

 

 

Revoke Group Membership

This is applicable for when you need to revoke (not reassign) a group membership

Given the example file above, you will need to flatten group columns into individual rows that reference the account's username.

API Details

Endpoint: https://SUBDOMAIN.ambition.com/api/v1/group_membership/
HTTP Request Verb: DELETE
Authorization Header: Authorization: Token API_TOKEN (Utilize a token from an existing API integration within Ambition or enable new API integration)
Content Type Header: Content-Type: CONTENT_TYPE

 

View of the Group Membership DELETE via the API Sandbox within Ambition.

Note - when utilizing the Delete functionality within the API Sandbox, you will not be able to view the payload since fields are being removed. However, you can reference the Group Membership POST for details. 

Screen_Shot_2020-09-28_at_4.01.29_PM.png

Related articles

Comments

0 comments

Article is closed for comments.