The purpose of the Salsa Engage API is to provide our clients with the ability to integrate with external systems or do custom analysis.
Currently the API provides the following end points to synchronize data from the Salsa platform and into a third party system.
- /api/integration/ext/v1/supporters - provides the ability to retrieve, update, and delete supporters using a supporter id
- /api/integration/ext/v1/supporters/search - provides the ability to search for supporters that have been modified within the system for a specific date range
- /api/integration/ext/v1/activities/search - provides the ability to search for activities (Donations, Targeted Letters, Signing Petitions) that supporters have taken action on
- /api/integration/ext/v1/metrics - provides the ability understand the operations invoked to date, current rate limit, and other insight data
Acquiring a Token
All calls made to the API are secured by the SSL protocol as well as an encrypted token that represents the identity of your organization.
You can acquire an API token for your account in Organization Settings -> API tab of Salsa Engage.
If no such tab is presented within the application, your organization does not have access or you Salsa Engage account does not have permissions to view that screen. Need access, but don't have it? Contact our helpful support team.
When viewing the API screen within Salsa Engage, the following will be displayed:
- Your API token that needs to be provided in the calls which looks something like:
- Metrics such as last call made as well as the total number of successful and failed calls
- The ability to re-issue a token in the event of there is a belief the current has been compromised.
- The previously issues token and the last time it was used - if applicable.
Call Rate Limits
Salsa Engage doesn't limit the number of concurrent processes that can access the API, but it does impose the following call rate limit:
Your token will allow:
- Up to 300 calls to the API within a 1 minute period
- Up to 20 items included in batch/bulk calls - this includes multiple supporter updates as well as searching and pagination calls
- Each item in a batch counts as 1 call and will be counted for the 1 minute period. For example 15 calls with a batch of 20 equates to 300 calls and will cause rate limiting to be enforced.
- Rate limiting is performed with a rolling 1 minute window - this means you can not perform 300 operations at the end of one clock minute and immediately send 300 more calls when the next clock minute occurs.
- If your organization requires a higher call rate limit, you can speak to a sales representative to discuss increasing it.