API - General Use

Call Request/Responses

The Salsa Engage API is a RESTful API that accepts and produces JSON payloads.

You need to ensure that the libraries you are using to make calls to the server set the request/response mime-type to application/javascript, if that is not done, then the proper conversion of the payloads may not occur and will be rejected by our server or your client

 

Error Codes Returned

There are two classifications of errors reported by the API

  • System level errors which indicate that something went wrong with during the processing, your token is not valid, or you have exceeded the call rate configured for the token.
  • Validation level errors when adding or updating supporter records

All system level errors will be reported as standard(or soon to be standard HTTP errors, following is the list of the errors you may encounter

Error CodeDescriptionDetail

400

Bad Request - Directives in your payload were invalid

This error would typically occur if the parameters for a search operation are not configured correct. Such an example is a activity search request without the modified From attribute set within the payload. In addition to the 400 code, the system will include a description for what the problem was. For example 200 Bad Request - Either 'modifiedFrom' or 'activityIds' must be provided.

401 Unauthorized Returned when a request without a valid token is made
429 Too Many Requests

A 429 error code will be returned in one of two cases. Either the call rate for the token has been exceeded, or the batch size requested for an operation is larger than what is configured for your token.

In either case the 429 will be returned with either one of the following messages:

429 Call rate has been exceeded

429 Requested batch size exceeds the allowed size of: <token batch size value>

500 Internal Server Error

Non recoverable error has occurred.

This exception will also include a JSON structure in the body with additional contextual information which could be provided to Salsa for troubleshooting.

You should be aware that some of these errors reported in this manner can be resolved on your end. An example of  such an error is providing an incorrect date format for a search condition.

 

 

Validation Codes Returned

Specific to Supporter management(E.g. Updates/Adds), the server will return contextual errors within an entity of a payload. These validation errors indicate that the values provided for the entity are not of the correct type, too large, or are missing.

Following is the list of validation error codes you may encounter:

Error CodeDescriptionDetail
2001 Field Required A value for the field identified within the error object is required

2007

Field out of range The value for the attribute is too long

2008

Invalid Email Address The provided email address appears to be invalid.
2011 Invalid Value

The value provided was not one of the allowed types. The error message will indicate both the field in error as well as the allowed types 

 

Validation Error for an Invalid Email Address

{
   "errors":[{"id":"a8e78523-7ac1-4132-9480-e15b88ae3de5","code":2008,"message":"The email provided is not of correct format","details":"Domain contains illegal character","fieldName":"value"}],
   "type":"EMAIL",
   "value":"bad@bad@com",
   "status":"OPT_IN"
}

 

Understanding Available Calls remaining

The API provides an end point that enables you to programmatically understand how many calls are available before making a request. The returned payload will include the count of available calls as well as operations that have been performed to date for the token.

 

GET /api/integration/ext/v1/metrics

  • Your authentication token must be set in the HTTP header as parameter   authToken=<your_auth_token> 

 

FieldDescription
rateLimit The rate limit configured for your token
maxBatchSize The maximum number of items you can include for a batch call
currentRateLimit Current point in time rate limit - how many calls that can be made before a 429 error will occur
supporterRead Number of supporter reads
totalAPICalls Number of API calls
lastAPICall ISO_8601 formatted String with a GMT timezone
totalAPICallFailures Number of API calls that failed
lastAPICallFailure ISO_8601 formatted String with a GMT timezone
supporterRead Supporter read count
supporterAdd Supporter add count
supporterUpdate Supporter update count
supporterDelete Supporter delete count
activityEvent Event activity read count
activitySubscribe Subscribe activity read count
activityFundraise Fundraise activity read count
activityTargetedLetter Targeted Letter activity read count
activityPetition Petition activity read count
activitySubscriptionManagement Subscription Management read count

CURL Example:

curl -H "authToken:$AUTHTOKEN" https://api.salsalabs.org/api/integration/ext/v1/metrics

Response Example:

{
  "id": "8a9aa3a2-083a-4826-88e8-a292d5af1f25",
  "timestamp": "2016-05-27T15:14:07.027Z",
  "header": {
    "processingTime": 64,
    "serverId": "ignite-small3.lab.salsalabs.net"
  },
  "payload": {
    "rateLimit": 300,
    "maxBatchSize": 20,
    "supporterRead": 0,
    "supporterAdd": 0,
    "supporterDelete": 0,
    "supporterUpdate": 0,
    "activityEvent": 0,
    "activitySubscribe": 0,
    "activityFundraise": 0,
    "activityTargetedLetter": 0,
    "activityPetition": 0,
    "activitySubscriptionManagement": 0,
    "totalAPICalls": 0,
    "totalAPICallFailures": 0,
    "currentRateLimit": 300
  }
}
Have more questions? Submit a request
Powered by Zendesk