In This Article:

    General Use

    In This Article:

      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 Code Description Detail


      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 Code Description Detail
      2001 Field Required A value for the field identified within the error object is required


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


      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"}], 

      Understanding Available Calls Remaining

      The API provides an endpoint 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> 
      Field Description
      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"

      Response Example 

        "header": {
          "processingTime": 64,
        "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,
          "offlineDonationAdd": 0,
          "offlineDonationUpdate": 0,
          "totalAPICalls": 0,
          "totalAPICallFailures": 0,
          "currentRateLimit": 300
      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request



      Article is closed for comments.