What can I learn from this page? | Guidance on setting up and using the Culture Amp API |
Who is this guide for? | Account Admins |
đ Note:
Our API is RESTful, allowing one-way outbound data retrieval. Currently, it doesn't support data ingestion
Data available from the API is limited to what is currently listed in the Culture Amp API Developer Portal.
Access to the API is included as part of your normal Culture Amp subscription fees and is there is no additional cost.
To learn more, check out our FAQs.
If you are having an issue with the API, please speak with a Product Support Specialist by replying with âAsk a Personâ in a Support Conversation
Our Culture Amp API allows you to securely get your account data from the CA platform for use in your systems.
To do this, a developer in your team needs to set up and manage it.
Understanding API Credentials
Access to our API is managed by API credentials using OAuth 2.0 Client Credentials Flow.
API Credentials are needed to make valid requests to the API and receive responses. They only let you access data in your Culture Amp account.
Credentials always control data access at the account level and canât be delegated to controlling data access for individual organisations, divisions or teams currently.
Credentials have âscopesâ which determine what type of data can be accessed from the API using a given credential, in addition to the types of calls that can be made using it (like GET calls for data retrieval).
Control of API Credentials
An API credential can only be created, edited or deleted by users with Administrator privileges via their Admin Settings.
Your organisation can create multiple API Credentials at any time to modularly control data access.
All credentials can also be edited or deleted at any time by Administrators.
If you delete a credential, it stops any more data access with it. This action can't be reversed, so it's crucial to be careful. Deleting might affect custom integrations or features leveraging that credential for data access.
Credential Sensitivity
Credentials control access to all data available via the API.
They are highly sensitive for this reason and must be treated with significant caution. Never share them with anyone you donât entrust with accessing your organisationâs data, including Culture Amp Support.
Creating API Credentials
Once youâve logged into Culture Amp as an Administrator, simply:
Open your Settings page.
Click on the API tab via the left-hand side menu.
Follow the prompts to create an API credential.
Share these credentials with your development team. Please ensure the sharing and storage of these credentials are done in accordance with your organizations security policies.
Using Your Credentials to Make API Calls
Provide the credentialâs client ID and client secret to your development team.
Direct your development team to our API Developer Portal for guidance.
Authorisation scopes must be included in the authentication request.
The developer can use the access token to make valid calls to the API endpoints listed in the Documentation above.
Editing API Credentials
Credentials can be edited at any time by users with Administrator privileges to change their titles or scopes.
Go to your Admin Settings
Click on API via the left-hand side menu.
Find the credential you wish to edit and click the Edit icon
Once youâve finished editing, click Save to make the changes to the credential. Any unsaved changes will not be applied to the credential.
đ Note: Changing credentials can break access for software which uses the credential for API access, in addition to blocking developers from accessing endpoints with scope changes. If youâre administering credentials, check with your developers before making any changes.
Deleting API Credentials
Credentials can be deleted at any time by users with Administrator privileges to prevent any further data access from being made using them. Deleting credentials carries a high degree of risk if they are being actively used or have features which rely on them which can break when the credential is deleted. Ensure you confirm with your developers or technical stakeholders prior to making credential changes or deletions.
Go to your Admin Settings
Click on API via the left-hand side menu.
Find the credential you wish to delete and click the View icon
Click Delete Credential and approve the deletion
Additional Info / Helpful Tips
Check out our Culture Amp API Developer Portal which contains useful information on:
Getting Started with the API: introduction to using the API.
Getting Credentials: Generate credentials within your account's Admin Settings to set up API access.
Authentication: Authenticate to create access tokens that are needed to make requests to the API.
Authorisation Scopes: understanding and using the Scope Parameter.
Common Use Cases: Learn about common ways customers use the API.
FAQs: Questions frequently asked about Culture Amp's API.
And additional guides for Developers on:
API Reference Documentation: guides on making calls and receiving responses from each API endpoint.
API Specification: Open API 3 Specification.
Pagination: Details of how API responses are paginated.
Usage Limits: Usage constraints in place to protect the API.
Security Information: Details on the API's encryption and security protocols.
Got feedback? Weâd love to hear how we can improve your experience in developing with Culture Ampâs API. Please share your thoughts here.
đŹ Need help? Just reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.