User API Integration
We advise working through the entire document if this is the first User API Integration that your Organization has set up within Ambition as this serves as a comprehensive guide to setting up the User API Integration.
How do I enable the User API Integration?
What types of User information can I send to Ambition?
How do I create field mappings?
Can I see an example of how a file would be mapped?
Enable the User API Integration
1. Log in to your Ambition instance.
2. Open the left navigation and click Administration > Data > Integrations.
3. Under Available Integrations, click the Enable Integration button in line with the User API Integration. You will be redirected within the new User API Integration.
Two User API Integrations can be enabled with the same Ambition instance. If your Organization has a use case for needing three or more User API endpoints, reach out to gethelp@ambition.com for more information.
Upon enabling you will be redirected within the Integration. To enter the API Integration anytime after original enabling:
Once enabled, the API Integration will appear under Active Integrations at the top of the page.
4. Click the Settings button to enter the API Integration.
5. Set a descriptive name for Integration Name. The default name is User API Integration. If multiple User API Integrations are being used, we recommend an explicit name, typically the data being transmitted. Ex. NA Sales Team User API, EMEA User API.
6. Provide an Admin Email Address. This email will be contacted if and when integration issues arise.
7. Click the Save button.
Set the File Format
You've now enabled the User API Integration, but Ambition needs to be instructed on how to handle your data.
Here you will indicate what type of file format will be sent to Ambition. CSV or JSON.
1. Within the User API Integration, click on Data Format.
2. Locate the File Format options. Set the File Format to either CSV or JSON.
3. Click the Save File Format button.
API Field Mappings
You will define and map the data to be transmitted.
If your File Format is CSV, then you will be mapping your spreadsheet's named column headers.
If your File Format is JSON, then you will be mapping your key names.
Ensure that these Field Keys are updated to match the formatting, including capitalization, of your actual headers or keys.
API Fields: How the field is identified within your file, either a key or column header. 43 character limit.
↳ email, first_name, and last_name are mapped upon enabling as Email, First Name, and Last Name are required to create and update users. Update the respective API fields to match your CSV columns or JSON keys.
Ambition Fields: Ambition data point that API Field represents.
Ambition Field Mapping Options
Pro Tip → If your Organization has already created Users, referencing the User Directory download can provide examples of each Ambition Field and the CSV that can be amended, optionally converted into JSON, and then used as the file to be transmitted through the User API.
| Ambition Fields | Field Type Descriptions |
| User - Email |
Required. Field containing the User's email as it should appear in Ambition. Ex: travis.truett@yourcompany.com ____ Ambition will use Email as a uniqueness constraint for Users. If a User has multiple @company email addresses (ex. travis@yourcompany.com and travis.truett@yourcompany.com), select a single, most reliable email to be tied to that User. Ambition will not overwrite a User's email address via the User API, but create a new account for each email address. If a User's email needs to be updated, you can make those changes in their settings |
| User - First Name |
Required. Field containing the User's First Name as it should appear in Ambition. |
| User - Last Name |
Required. Field containing the User's Last Name as it should appear in Ambition. |
| User - Username |
Required for Organizations using the Salesforce Integration. Field containing a User's Salesforce Username ____ If your Organization uses our Salesforce Integration, include an additional column/key containing Salesforce Usernames as they appear in your Salesforce Org. Salesforce Usernames must in the form of an email address, xxxx@xxx.com. |
| User - Time Zone |
Optional. Field containing the respective time zone for where the User is located. ____ If CSV file format, if this column is included every row must have a value. |
| User - Manager Email |
Optional. Field containing the email of the User's respective manager. Manager Email will update the Manager field in a User's Ambition settings. ____ The Manager must already exist as a User in Ambition. If the User's email in the Manager Email field does not have the "Is Manager" permission, Ambition will automatically assign it during the upload process. If the cell is empty it will clear an existing Manager if previously set. If the Manager Email does not belong to an existing User in Ambition it will clear an existing Manager if previously set. |
| User - Is Active |
Optional. Field containing True or False that can be used to deactivate users. |
| User - Is Manager |
Optional. Field containing True or False to assign a User Manager Permissions in Ambition. ____ If CSV file format, if this column is included every cell must have a value. If you are updating an existing User from True to False ensure that the User is no longer managing any Groups, otherwise Ambition will not make a change. |
| User - Is Admin |
Optional. Field containing True or False to assign a User Admin Permissions in Ambition. ____ If CSV file format, if this column is included every cell must have a value. |
| Integration |
Optional. Field containing the respective Integration ID for a specific integration other than Salesforce. ↳ Ex: Phone Extension, Employee ID. ____ Correlating data integrations must be established first before Integration IDs can be uploaded. Reach out to gethelp@ambition.com with questions. Since Integration IDs are a 1:1 mapping, you are unable to map a single column/key to multiple Integration IDs. We recommend adding a separate column/key for each respective Integration ID.
To ensure proper mapping, the following naming convention will be used in the Ambition Field mapping options. "Integration ID Field Name (Integration Name)" Ex. |
| Group |
Optional. Field containing the name of an existing or new Group that the User is a member of. ____ Ambition will automatically create Groups that do not currently exist in Ambition. Group Types will not be created through this process. Only existing Group Types can be selected as mapping options. |
Create Field Mappings:
1. Click the Add button.
2. Fill in the API Fields for each CSV column header or JSON key, and select the appropriate Ambition Field mapping.
API Fields: How the field is identified within your file, either a key or column header.
Ambition Field: Ambition data point that API Field represents.
As noted above:
Ensure that these Field Keys are updated to match the formatting, including capitalization, of your actual headers or keys.
Update the email, first_name, and last_name API fields as needed to fit your Data Format.
3. Once the Data Format is complete, click the Save API Field Mappings button.
Users can now be managed through the User API Integration.
Learn how to transmit data to the User API Integration here.
Example File with Corresponding Ambition Mappings
Example file to be sent to Ambition.
| First Name | Last Name | Time Zone | Role | Location | Team | Phone Extension | |
|---|---|---|---|---|---|---|---|
| Joey | Freshwater | joey@freshwater.com | America/New_York | Account Executive | East | Alpha Dogs | 4233 |
| Agnes | Goodman | agnes@goodman.com | America/Los_Angeles | Account Manager | NW | Omega Cats | 1233 |
Mappings of Example File above to Ambition Fields.
Comments
0 comments
Please sign in to leave a comment.