Articles in this section

How do I integrate user management?

Avatar
Travis Truett
  • Updated
Follow

User Provisioning API

Use the User Provisioning API to automatically sync users and groups from an existing system to Ambition.

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

 

Users

Creating / Updating

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
1  Jason Smith jason@yourcompany.com jason@yourcompany.com
 1  Susan Simpson  susan@yourcompany.com susan@yourcompany.com

 

All Supported Fields

View all supported fields 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.

 

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/

 

Deactivating

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

You can create and deactivate users with a single request

 

Groups

Creating / Assigning 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 and Group Types or you can create your 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
  2. Create Group
  3. Add exiting Users to Group
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/

 

Revoking 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

Related articles

Comments

0 comments

Article is closed for comments.