Section 1: Overview
Welcome to the 10KC API Beta! This new feature is designed to enhance the way you manage and understand employee engagement within your organization.
Subsection 1.1: What is the 10KC API?
The 10KC API stands for Ten Thousand Coffees Application Programming Interface. It's a powerful tool that lets you automate the reporting of employee data directly from the 10KC platform to your internal systems or dashboards.
Subsection 1.2: Benefits
Integrating the 10KC API into your reporting tools offers several benefits:
- Real-time Insights: Stay up-to-date with the latest adoption, engagement, goal, and interaction metrics. Real-time data helps you react and adapt your strategies promptly.
- Streamlined Reporting: Eliminate manual data entry and automate your reporting process. Save time and reduce errors by directly importing data into your preferred systems.
- Customizable Data Integration: Choose which data points are most relevant to your needs. Whether it's tracking overall platform adoption or drilling down into specific engagement metrics, the 10KC API gives you the flexibility to tailor your analytics.
Subsection 1.3: What data is accessible?
You can integrate a variety of member data elements into your internal employee data systems or dashboards. We’ve outlined a few below.
Adoption
- created_at: The date a member was added to the platform, which can help track new user adoption over time.
- _id: Each member's unique identifier, counting these can show total platform adoption.
- join_date: when the member joined.
- signup_method: how a member sign-ups (email invite, SSO, Microsoft Teams integration).
Engagement
- last_login: when the member last logged in.
- last_active: when the member was last active.
- introductions: Indicates whether a member introductions enabled or disabled.
- intro_count: The number of introductions a member has received.
- received_message_count: How many messages a member has received.
- sent_message_count: The number of messages a member has sent.
- office_hour_waitlisted: how many events the member is on a waitlist.
- office_hour_confirmed_participant: how many events the member registered for.
Profiles attributes (goals, roles, and segments)
These attributes are important for matchmaking and reporting.
- interests: the interests the member has selected.
- seeking: professional development goals a member is seeking to achieve.
- offerings: areas where they can offer opportunities to others for professional development and networking.
- You can also see which roles and segments are filled out for the member’s profile.
Section 2: Give us feedback!
Your feedback is crucial—it influences the API’s development, helping us refine its functionality and ensure it integrates seamlessly with your systems. It's about more than just identifying bugs or technical issues; it's about shaping the API into a tool that truly meets your needs and expectations.
Subsection 2.1: How to provide feedback
Email us by using the product support form. Directly share your thoughts, suggestions, and any issues encountered. Your detailed insights, whether positive or improvement suggestions, are welcomed.
Subsection 2.2: What feedback to provide
Focus on areas such as:
- Data usefulness: How does the API’s data enhance your operations? What additional data do you need?
- Integration experience: Feedback on ease of use, documentation clarity, and desired functionalities.
- Success stories: Your successes with the API will inspire us.
Section 3: Accessing the API
Subsection 3.1: Prerequisites
To kick things off with the 10KC API, there are a few prerequisites and steps to follow:
- Create a 10KC Admin Account: An admin account is necessary to access API settings and manage keys.
- NodeJS v20+ needs to be installed on your machine with the Axios NPM package.
- Create an API Key:
- Go to Admin Settings in the top navigation bar.
- Select API Keys from the left navigation menu.
- Click on "Add new," enter a name for your API key, and click "Create."
- Securely copy your API key. It's crucial to keep this key confidential to maintain security.
Storing an API key in an environment variable
10KC recommends storing your API key in an environment variable or a config file that is not stored in version control.
When setting a variable in your program, that variable is readable by any person or system that can access the text file where it’s set. However, a variable that's confined to the environment where the code is executed, stored outside the program itself, is called an environment variable. Only people and programs with access to the environment can read the value assigned to an environment variable. This makes environment variables a more secure choice for storing credentials such as API keys.
Deleting an API Key
Once you delete a key, it can no longer be used to access 10KC's API services.
Click the Delete button in the same row as the key you want to delete. Select Delete API Key. This will delete the key permanently, making it inactive. 10KC will reject any subsequent API calls using this deleted API key.
Subsection 3.2: Requesting member data
Integrating the 10KC API into your system involves a few coding steps, particularly for requesting and downloading a CSV file of member data. Here's a simplified guide:
1. Identify Your hub's details.
- Navigate to the 10KC Hub and the specific member group you're interested in.
- Note down the SUBDOMAIN and GROUP_ID from the URL. For example: https://<SUBDOMAIN>.tenthousandcoffees.com/hub/puppy-treats-cafe/members?group=<GROUP_ID>
2. Set up your request.
- Using the NodeJS script provided, replace API_KEY, GROUP_ID, and SUBDOMAIN with your specific details.
NodeJS Script
const axios = require('axios');
const fs = require('fs');
const API_KEY = 'API_KEY';
const GROUP_ID = 'GROUP_ID';
const SUBDOMAIN = 'SUBDOMAIN';
const pollInterval = 1000; // Milliseconds between requests
async function pollEndpoint(taskId = '') {
try {
const response = await axios.get(`https://${SUBDOMAIN}.tenthousandcoffees.com/api/v2/groups/${GROUP_ID}/files/members-csv/download/${taskId}`,
{
headers: {
Authorization: `Bearer ${API_KEY}`,
},
});
if (response.status === 200) {
console.log('Members CSV is ready');
fs.writeFileSync('members.csv', response.data);
process.exit(0);
}
if (response.status === 202) {
console.log(`Server responded with status code ${response.status}. Retrying in ${pollInterval}ms...`);
setTimeout(() => pollEndpoint(response?.data?.taskId), pollInterval);
} else {
console.error(response);
process.exit(1);
}
} catch (error) {
console.error('Error:', error);
process.exit(1);
}
}
pollEndpoint();
Need help?
For further assistance don't hesitate to contact the product team.
Related to
Comments
0 comments
Please sign in to leave a comment.