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.
Example File Exported from HRM System
first_name | last_name | 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.
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 | 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.
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.
2. Create Group via POST to /group.
3. Add exiting Users to Group via POST to /group_membership.
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.
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.
Comments
0 comments
Article is closed for comments.