API

15Five's Public Application Programming Interface (API) allows 15Five administrators to read and modify data within their 15Five account via custom built integrations, allowing increased flexibility working with your own HR system. Continue reading for information about setting up tokens and 15Five API support, or visit our Public API Documentation for technical details and capabilities.

In this article, you will learn...

• How to generate an API access token in 15Five
• What features are supported by 15Five's API
• Troubleshooting and support
• FAQs

Generate an API access token

1. Click on the settings gear in the top, right-hand corner of 15Five.
   
2. Select 'Features' from the dropdown menu.
   
3. Scroll to the bottom of the page and click on 'Integrations'.
   
   
4.  Click Enable to the right of the Public API option.
   
5. Once enabled, you'll land on the 'Company API keys' page. Click the Create new key button.
   
6. Add in a short name for your API key. This name can be anything, but we suggest using a name that's easily identifiable from your server-side. If you would like to limit the API access to High Fives only, check that box before saving. Then, click Save.
7. You will be redirected back to the 'Company API keys' page to verify your API key and access token.
   
   The Public API key is 32 characters long. Not to be confused with the SCIM key, which is 30 characters long.
   The endpoint for your API, assuming you do not have a unique subdomain, is my.15five.com.
8. Use the access token to link 15Five's API to your server.

Features supported by 15Five's API

To see what features In 15Five we support for API, or to see example reports of each export, check out our Public API Documentation. If you have any issues seeing this list, please reach out to support@15five.com.

Troubleshooting and support

Email invites aren't going out.

Problem: Employees who were uploaded through the API didn't receive an email invitation.

Solution: There are a few reasons an invite email may not have been sent out:

• The 'send_welcome_from' field wasn't populated correctly. You need to have the column 'send_welcome_from' within the CSV file filled in with the email of the person you want to be the inviter (i.e. that you want to appear as the sender of the welcome email). You can use 15fivebot@15five.com if you prefer the email to be sent from 15Five.
• Your company invite settings are set up to not send out email invites. If your company invite settings are set to "Don’t send invites immediately after import," invite emails will not be sent out.

New users added to the import CSV aren't being imported.

Problem: Although you're adding new employees to the CSV, accounts aren't being created for them.

Solution: Possible reasons new users aren't being imported are...

• The email address contained in the 'send_welcome_from' column isn't either 15fivebot@15five.com or an email associated with an active 15Five account for your company. If you use an email address that isn't associated with an active 15Five account, employees won't be added.
• You imported a new user and without including an email address. Even if you use employee ID as a unique identifier, you must include an email address to create new accounts in 15Five. If you try to upload new users without including an email address, you will receive an error message.

Updates made in the import CSV aren't being reflected in the API.

Problem: You made updates via import CSV in the API, but don’t see the updated information.

Explanation: The syncing process can take between 10 to 20 minutes. For a brief period of time, you might see imported users without the correct reviewers assigned. Reviewers are assigned as the next step after importing (creating) users, so after seeing that all users have been imported, please wait a few extra minutes before checking if they have correct reviewers (and smart groups) assigned.

FAQs

• Q: If I choose to use employee ID as the unique identifier for new users, do I need to do anything specific?
  A: Yes. When adding new employees to 15Five using employee ID as the unique identifier, you must also include an email address for each new user. Reason being, employees must sign in with an email address, and if we don't have one on record for them, they cannot log in. After the initial upload, you can choose to only use employee ID as the unique identifier.
• Q: Where can I find the export.csv so I can know the exact format to use?
• A: For a list of all column headers and what information 15Five can ingest, please go to your 'Bulk import' page (in-app link).
  
• Q: Does 15Five have API call limits?
  A: Yes. Currently, we have rate limits per server per IP address. However, we will be working in the future on more accurate rate limits for our Public API.
• Q: Does 15Five support SFTP?
  A: No. However, you can post a CSV to our API. This is technically equivalent. https://15five.15five.com/api/public#bulk-user-import-create
  
• Q: When uploading or adding users via API is there an option to block invite emails? If so, what does this look like?
  A: Yes- you can essentially disable the invite email by not filling out the column 'send_welcome_from'. Simply do not use that column in your CSV file.
  
• Q: What are the API visibility settings?
  A: The API key is only accessible in the application to account admins, but those admins can of course choose to give it to someone else on their team to use.
  All objectives are fully available via the API and are not masked in any way, regardless of their privacy settings.
• Q: Can we create objects through your API?
  A: Unfortunately, this is not an option through the API.
• Q: What are the file specs: new users, terminated users?
  A: New users will automatically be created if their email address is not already associated with a 15Five account. To terminate/deactivate users, use "N" (for no) in the 'is_active' column for all users you want to deactivate.
• Q: Do I have to create groups in 15Five before using the import 'add_to_groups' or 'active_groups' columns?
  A: No. Groups can be pre-created from directly within 15Five OR groups can be created and members added simultaneously through your API. If 15Five recognizes a new group name in the columns 'add_to_groups' or 'active_groups' from your import, these groups will be created upon import. 
• Q: How do I set up the automatic creation of groups?
  A: You don’t need to change the CSV file itself. Instead, you should change the permitter for when you send the file. That is found here. There is a flag that says I want to create groups if they do not exist. In pink text under 'Create groups' in the CSV import section. This is a small modification on your end. You will need to have someone who knows how to code to do this.
• Q: Do you allow automatic change of group membership when users change departments?
  A: We usually recommend using the columns 'add_to_groups' and 'remove_from_groups' to change group membership. This allows 15Five unique groups to stay unaffected by any changes. Please note any changes made in the 'active_group_names' will override any current group settings (i.e. leaving the 'active_group_names' field empty for a user will remove them from all groups).
• Q: Can we get an option to cancel imports or view logs for them ourselves?
  A: This option is only available for 15Five employees on the backend.
• Q: How can we assign group admins when creating groups via the API?
  A: There is no way to pass over a group admin. The field for group admin will be blank in 15Five after API push. After the groups are created in 15Five you can add a group admin by following these steps.
• Q: How does the API determine who the “reviewer” is? Is that auto-populated by the “manager” field in UltiPro or other third parties?
  A: No. All reviewers have to be included in the API via the 'reviewer_email' field in the CSV.
• Q: I have been planning on using only the 'bulk_user_import' for all imports including user updates. Is this recommended? Is there a more recommended way to update users?
  A: Our Engineers recommend using User - Update https://15five.15five.com/api/public/#user-update
• Q: Can we use the API to send over Vacations that employees put into People HR or other HRIS platforms?
  A: Unfortunately, this is not available via the API.
• Q: What does it mean if the CSV file being uploaded via the API status is set to “Scheduled”?
  A: If the file is getting stuck in "scheduled," there’s an error. Please share your CSV with us so that we can help assist.
• Q: Can I use PowerShell’s (Microsoft) “Invoke-WebRequest” cmdlet to call into 15Five’s POST bulk-user-import web service. How would I be able to do that?
  A: From the Microsoft documentation, it should definitely be possible. Here's a script that should be working: $URI, $Headers, and $FilePath parameters should be modified to reflect your needs. The CSV file should NOT contain the UTF byte marker. Document of script Untitled
• Q: Why am I being taken to this article when searching for Zapier?
  A: We sunset our Zapier integration and, as an alternative, recommend using 15Five's API. If you have further questions or suggestions about things you want to be able to accomplish via the API, reach out to our Support Team by emailing support@15five.com.