In This Article:

    Salsa Application Program Interface (API)

    In This Article:

      Salsa provides an API that lets applications read to and write from the Salsa database. Security is provided by an authentication call. The authentication call returns a token in the form of a cookie, and the token cookie is provided with all subsequent calls.

      This section of the Salsa documentation

      • describes all of the API calls,
      • describes the parameters that the API calls use,
      • provides best practices and warnings, and
      • provides examples of how to use the API calls.

      API Call Summary

      /api/authenticate.sjs

      Provides security credentials to Salsa. Passing authentication means that the application has access to the database.

      /copy

      Creates a copy of a record in the database.

      /delete

      Completely and irreversably removes a record from the database.

      /api/describe2.sjs

      Returns a record that describes the fields in a database table.

      /api/getCount.sjs

      Return a count of records that match criteria provided in the URL.

      /api/getCounts.sjs

      Retrieve many records from a single table.

      Provide a variety of count values that match criteria provided in the URL.

      /api/getLeftJoin.sjs

      Retrieve records by joining two or more tables.

      /api/getObject.sjs

      Retrieve a single record from a table using the primary key.

      /api/getObjects.sjs

      Retrieve more than one record from a table using the provided conditions

      /api/getReport.sjs

      Run a report, optionally supplying parameters, and retrieve the report output.

      /api/getTaggedObjects.sjs

      Retrieve records that are tagged with a particular tag value.

      /save

      Save or updates a record in the database.

      /api/tagObject.sjs
      Tag a record with a tag value.

      API_HOST

      When you see API_HOST in an example, that indicates that you should use the Salsa hostname for your organization. Here are some steps that you can use to get that:

      1. Edit a donation page and view it.
      2. If you're unable to edit a donation page, then find and view any donation page for your org that's hosted on Salsa.
      3. The API_HOST is the hostname in the browser's address bar. The hostname name appears after 'https://' and before the next slash.


      Here are some example:

      If you have questions about the API_HOST, then send us a message on developers@salsalabs.com and we'll be glad to help.


      authenticate.sjs

      provide security credentials to gain access to the database

      API_HOST/api/authenticate.sjs?email=&password=[&json][&xml] Parameters

      The parameters specify the email address and password for a Salsa campaign manager. Salsa strongly recommends that the email address and password for an application be just for the application, and not for the developer that creates the application.

      Required parameters
      email

      Campaign manager's email address.

      password

      The password for email.

      Optional parameters
       
      xml

      Set the returned format to XML

      json

      Set the returned format to JSON

      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml

      Set the returned format to XML

      json
      Set the returned format to JSON

      Examples

      Authenticate with Salsa using valid credentials.
      API_HOST/api/authenticate.sjs?email=my@email.address&password=secret!password!

      Returns:

      XML Results
      <?xml version="1.0"?>
      <data organization_KEY="8564">
          <message>Successful Login</message>
      </data>
      JSON Results
      {"jsessionid":"E727DBBB3BEB0D34CE7E102DBFDEFE37-n3","status":"success","message":"Successful Login"}
      Authenticate with Salsa using invalid credentials.
      API_HOST/api/authenticate.sjs?email=my@email.address&password=bad,bad password...

      Returns:

      XML Results
      <?xml version="1.0"?>
      <data>
          <error>Invalid login, please try again.</error>
      </data>
      JSON Results
      {"jsessionid":"E727DBBB3BEB0D34CE7E102DBFDEFE37-n3","status":"error","message":"Invalid login, please try again."}

      Best practices

      1. Assign credentials to the application and to the developer. Have the developer provide a way for the app to have its credentials changed. This will provide mutual security for your org and the developer since the developer will not know the app's credentials without the organizations permission after development is complete.
      2. Campaign manager email addresses can contain any non-empty string. Credentials for an application need not be in the format of an email, and can be anything that makes sense to the organization.
      3. The authentication cookie must be presented to all API calls after authentication. The recommended practice is to use an HTTP library that retains and presents the cookies in the correct formats.
      4. Check for success after authentication. The credentials in your app may have been revoked, and your app should be prepared to handle that possibility gracefully.
      5. An authentication session lasts about two hours. If your application will run more than that amount of time, then it should be prepared to authenticate more than once.

       

      /copy

      create a new record by copying existing record

      API_HOST/copy?object=&key=

      The /copy API call creates a new record in the database using the record specified by the key as the source.

      Parameters Required parameters Required parameters
      object
      The object parameter that specifies the database table name
      key

      The key parameter is the primary key for a record. Note: The primary key for table is always table_KEY.

      Optional parameters
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Examples
      Copy the donation with a good primary key to create a new donation.
      API_HOST/api/copy?object=supporter&key=12345

      Returns:

      XML

       

      JSON

       

      Copy the donation with invalid primary key to create a new donation.
      API_HOST/api/copy?object=supporter&key=999999999

      Returns:

      XML

       

      JSON

       

      /delete

      completely and irretrievably delete a record.

      API_HOST/delete?object=&key=

      The /delete API completely and irretreivable deletes the record with primary key key. The record is removed from the database and cannot be recovered except by requesting a database restore from Salsa.

      Parameters Required parameters Required parameters
      object
      The object parameter that specifies the database table name
      key

      The key parameter is the primary key for a record. Note: The primary key for table is always table_KEY.

      Optional parameters
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Examples
      Delete a donation record using a valid primary key.
      API_HOST/api/delete?object=supporter&key=12345

      Returns:

      XML

       

      JSON

       

      Delete a donation record using an invalid primary key.
      API_HOST/api/delete?object=supporter&key=999999999

      Returns:

      XML Results

       

      JSON Results

       

      describe2.sjs

      describe the contents of a database table

      API_HOST/api/describe2.sjs?object=tablename

      The describe2.sjs call describes the fields in a Salsa table. Details are provided about the datatype and size of each field

      Parameters Required parameters
      object
      The object parameter that specifies the database table name
      Optional parameters
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Examples
      Retrieve the format of the supporter table:
      API_HOST/api/describe2.sjs?object=supporter
      Retrieve the format of the donation table:
      API_HOST/api/describe2.sjs?object=donation
      Retrieve the format of the tag table:
      API_HOST/api/describe2.sjs?object=tag

      getObject.sjs

      retrieve a single object from the database using a primary key

      API_HOST/api/getObject.sjs?object=tablename&key=key

      The getObject.sjs call returns the single object from the database. The record has a primary key of key. Ths call returns an empty record if key does not identify a record.

      Parameters Required parameters
      object
      The object parameter that specifies the database table name
      key

      The key parameter is the primary key for a record. Note: The primary key for table is always table_KEY.

      Optional parameters
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Note on primary keys

      Primary keys in salsa are named using the table name where they reside. The generic format is [table]_KEY, where [table} is a database table name. Salsa database table names are singular except for the "groups" table. Here is a sample of tables and their primary keys:

      • supporter: supporter_KEY
      • donation: donation_KEY
      • supporter_action: supporter_action_KEY
      • groups: groups_KEY
      • supporter_groups: supporter_groups_KEY
      Examples
      Read the supporter record with key 12345 and return the results in XML.
      API_HOST/api/getObject.sjs?object=supporter&key=1234
      Read the donation record with key 548956 and return the results in JSON.
      API_HOST/api/getObject.sjs?json&object=donation&key=548956

      getObjects.sjs

      return more than one object from the database

      API_HOST/api/getObjects.sjs?object=tablename&condition=...&orderBy=...&limit=...&include=..

      The getObjects.sjs call retrieves records from the database. In its simplest form, getObjects.sjs will return an array all of the objects available. In its more complex forms, getObjects.sjs can retrievs records that match criteria provided by the developer.

      Parameters Required parameters
      object

      The object parameter that specifies the database table name

      Optional parameters
      condition

      Limit the records by record value. A getObjects.sjsstatement can contain zero, one or many condition parameters. The condition parameter is analgous to the WHERE clause in a SELECT statement.

      include
      Limit the fields that are returned for each record. The default behavior is to return all fields.
      limit
      Limit the number of records returned to a specified count. The default is to return all matching records in chunks of 500 records.
      orderBy
      Set the sort order for returned records. Records can be sorted by any number of fields in both ascending or descending order.
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Examples
      Read all supporter records
      API_HOST/api/getObjects.sjs?object=supporter
      Read the first 15 supporter records
      API_HOST/api/getObjects.sjs?object=supporter&limit=15
      Skip 1000 donation records and read 15
      API_HOST/api/getObjects.sjs?object=donation&limit=1000,15
      Read 20 supporter records where the first name field is "Bob"
      API_HOST/api/getObjects.sjs?object=supporter&condition=First_Name=Bob&limit=20
      Read the action_KEYs for a supporter with supporter_KEY 12345
      API_HOST/api/getObjects.sjs?object=supporter_action&condition=supporter_KEY=12345
      Read the donations for a supporter with supporter_KEY 12345 that were made after October 15, 2013
      API_HOST/api/getObjects.sjs?object=donation&condition=supporter_KEY=12345&condition=Transaction_Date>2013-10-15

      getLeftJoin.sjs

      join two or more tables to retrieve data

      API_HOST/api/getLeftJoin.sjs?xml&object=tablename&condition=&orderBy=&limit=&include=

      The getLeftJoin.sjs call allows you to use the mapping table to retrieve information about a supporter and the groups, events and actions that the supporter belongs to or attended. For example, you can use getLeftJoin.sjs to

      • Find all of the groups that a supporter belongs to
      • Read supporter information for everyone in a particular group
      • Find the email addresses for supporters that have taken one of many actions
      • Create a registration list for the supporters that are attending an event
      • Find all of the supporters in a group
      Background

      The Salsa database schema can be viewed as the supporter table surrounded by a a ring of other tables such as groups, action or events. The outer ring of tables are logically linked to the supporter table with many-to-many relationships. For example, a supporter can belong to many groups (groups), or may take many actions (action) or atte3nd many events.

      The supporter table is linked to these other tables via "mapping tables" in the database. The mapping tables hold a single record for each time that a supporter joins a group, or takes an action or attends an event. Each mapping table record contains at least the primary key for a supporter and a primary key for the other table (groups_KEY, action_KEY, etc.)

      Mapping tables are named for the two tables that they link, with supporter generally first in the name. For example, the supporter_groups links the supporter table to the groupstable to indicate the groups to which a supporter belongs. It can also be used to find the supporters that belong to a group.

      Parameters Required parameters
      object
      parameter that contains a description of the tables to be merged and the fields used to merge them. There are two general formats:
      • left(left-key)right and
      • left(left-key)center(right-key)right

      The first form is used to join two tables, for example groups and supporter. This is the most common object parameter used when calling getLeftJoin.sjs

      The second form is used to join three tables. An example is to retrieve supporter records and the detailed records for the actions that they have taken. In this caser, getLeftJoin.sjs joins the supporter and action table using the supporter_action as the mapping table.

      Note: In the second form, the mapping table is always the center table

      left
      is the table to used to select known values. In Salsa, left is usually the supporter table
      left-key
      is the primary key name for left table
      center
      (if used) is the many-to-many table that join left and right tables
      right-key
      is the primary key name for right table
      right
      is the table to use to look up values
      Optional parameters
      condition
      Limit the records by record value
      include
      Limit the fields that are returned for each record. The default behavior is to return all fields.
      limit
      Limit the number of records returned to a specified count. The default is to return all matching records in chunks of 500 records.
      orderBy
      Set the sort order for returned records. Records can be sorted by any number of fields in both ascending or descending order.
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Examples

      We get a lot of questions about how to do specific joins, so here is a sample of common joins that you might find helpful. All of the examples have been broken down to aid legibility. In reality, they are really loooong URLs.

      Retrieve the dates and amounts for donations made by the supporter with email address super@rich.person
      API_HOST/api/getLeftJoin.sjs
      &json
      &object=supporter(supporter_KEY)donation
      %condition=supporter.Email=super@rich.person
      &include=Tramsaction_Date,amount
      Retrieve the names for all groups where the supporter with primary key 123456 is a member:
      API_HOST/api/getLeftJoin.sjs
      ?object=supporter(supporter_KEY)supporter_groups(groups_KEY)groups
      &condition=supporter_KEY=123456
      &include=Group_Name
      Retrieve all of the names and email addresses for supporters in group 123456:
      API_HOST/api/getLeftJoin.sjs
      ?object=supporter_groups(supporter_KEY)supporter
      &condition=groups_KEY=123456
      &include=First_Name,Last_Name,Email
      Retrieve all of the names and email addresses for supporters in a group named "Big Spenders":
      API_HOST/api/getLeftJoin.sjs
      ?object=groups(supporter_KEY)supporter
      &condition=Group_Name=Big%20Spenders
      &include=First_Name,Last_Name,Email
      Retrieve the first name, last name, email, for all supporters who made donations in 2014. Also retrieve the transaction date and amount for each matching donation record. Records are sorted by the amount in descending order.
      API_HOST/api/getLeftJoin.sjs
      ?xml
      &object=supporter(supporter_KEY)donation
      &condition=donation.Transaction_Date%20LIKE%202014-%25
      &include=supporter.First_Name,supporter.Last_Name,supporter.Email,Transaction_Date,amount
      &orderBy=-amount
      &condition=supporter.First_Name%20IS%20NOT%20EMPTY
      Find the names and emails of all supporters in "Big Spenders" group that took part in the "Halloween Bash" event

      (Demonstrates getLeftJoin.sjs using more than one "center" table.)

      API_HOST/api/getLeftJoin.sjs
      ?xml
      &object=event(event_KEY)supporter_event(supporter_KEY)supporter(supporter_KEY)supporter_groups(groups_KEY)groups
      &condition=event.Name=Halloween%20Bash
      &condition=groups.Group_Name="Big%20Spender"
      &include=supporter.First_Name,supporter.Last_Name,Supporter.Email
      &order_by supporter.Last_Name,supporter.First_Name
      Cautions
      1. Keep in mind that Salsa will not return more than 500 records on a single getLeftJoin.sjs call
      2. Remember that you may have to disambiguate field names because the field may appear in more than one of the joined tables
      3. Joining two tables can return a lot of data. Doing the join incorrectly could really bog your application down
      4. If you are just scrolling through a table, then use getObject.sjs instead

      getCount.sjs

      Count records in the database that match the provided criteria

      API_HOST/api/getCount.sjs?object=tablename&condition=..

      The getCount.sjs call counts records in the database. In its simplest form, getCount.sjs will returns the count all of the objects available. In its more typical forms, getCount.sjs can count the records that match criteria provided by the developer

      Parameters Required parameters
      object
      The object parameter that specifies the database table name
      countColumn
      The countColumn parameter that specifies a column name to count. Generally, for object=[table], the countColumn parameter is [table]_KEY.
      Optional parameters
      condition
      Limit the records by record value
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON.
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml

      Set the returned format to XML

      Note: &json doesn't work correctly. use &xml instead.

      Examples
      Count all supporter records
      API_HOST/api/getCount.sjs?object=supporter

      Returns:

      <?xml version="1.0"?>
      <data organization_KEY="8564">
      <supporter>
      <count>1224</count>
      </supporter>
      </data>
      Count the number of supporters with a first name of "Robert"
      API_HOST/api/getCount.sjs?object=supporter&condition=First_Name=Robert

      Returns:

      <?xml version="1.0"?>
      <data organization_KEY="8564">
      <supporter>
      <count>10</count>
      </supporter>
      </data>
      Cautions

      At this writing, Salsa does not return the count in JSON format for a call like this:

      API_HOST/api/getCount.sjs?object=supporter

      If you need to count records, then please use &xml instead of &jsonuntil this problem is fixed.


      getCounts.sjs

      return counts, maximums and minimums for records that meet the provided criteria

      API_HOST/api/getCounts.sjs?object=tablename&condition=&countColumn=

      The getCounts.sjs call counts records in the database and does some basic calculations on the field values:

      • count
      • minimum
      • maximum
      • sum

      This can be handy for basic statistical analysis of numeric fields like donation amounts or custom fields. The minimums and maximums work on all data types, and can be used to find upper and lower bounds for names and dates.

      Parameters Required parameters
      object
      The object parameter that specifies the database table name
      Optional parameters
      countColumn
      The countColumn parameter specifies a field to count and perform calculations on. The default column is the primary key for table ( table_KEYfor the table name in object.)
      condition
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      countColumn
      The countColumn parameter that specifies a column name to count. The default value is the primary key for the table. Choose other fields to get useful information.
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Examples

      Some of the examples are broken down into separate lines for legibility. In reality, they are really loooong URLs.

      Get counts for the supporter table. Do not provide a countColumn
      API_HOST/api/getCounts.sjs?object=supporter

      Returns:

      <data organization_KEY="8564">
          <supporter>
              <count>
                  <count>1236</count>
                  <sum>68547805675</sum>
                  <max>56294113</max>
                  <min>52572523</min>
              </count>
          </supporter>
      </data>
      Counts the number of supporters with a first name of "Robert"
      API_HOST/api/getCounts.sjs
      ?object=supporter
      &condition=First_Name=Robert

      Returns:

      <data organization_KEY="8564">
          <supporter>
              <count>
                  <count>10</count>
                  <sum>561076599</sum>
                  <max>56151770</max>
                  <min>56059149</min>
              </count>
          </supporter>
      </data>
      Find stats for donation amounts in the month of December.
      API_HOST/api/getCounts.sjs
      ?xml
      &object=donation
      &condition=Transaction_Date%20LIKE%25-12-%25
      &countColumn=amount

      Returns:

      <data organization_KEY="8564">
          <donation>
              <count>
                  <count>375</count>
                  <sum>3323617.48</sum>
                  <max>400000.00</max>
                  <min>1.00</min>
              </count>
          </donation>
      </data>
      Find the smallest and largest names for donations in December. (This corresponds to the first and last items in a list of sorted first name fields.)
      API_HOST/api/getCounts.sjs
      ?xml
      &object=donation
      &condition=Transaction_Date%20LIKE%25-12-%25
      &countColumn=First_Name

      Returns:

      <data organization_KEY="8564">
        <donation>
          <count>
            <count>365</count>
            <sum>0</sum>
            <max>Wyatt</max>
            <min>Aaliyah</min>
          </count>
        </donation>
      </data>
      Find the earliest and latest transaction dates for donations in December
      API_HOST/api/getCounts.sjs
      ?xml
      &object=donation
      &condition=Transaction_Date%20LIKE%25-12-%25
      &countColumn=Transaction_Date

      Returns:

      <data organization_KEY="8564">
        <donation>
          <count>
            <count>375</count>
            <sum>7.536088000006651e15</sum>
            <max>Fri Dec 05 2014 13:19:42 GMT-0500 (EST)</max>
            <min>Tue Dec 14 2004 00:00:00 GMT-0500 (EST)</min>
          </count>
        </donation>
      </data>

      getTaggedObjects.sjs

      return records form the database that have a particular tag

      API_HOST/api/getTaggedObjects.sjs?object=tablename&condition=...&orderBy=...&limit=...&include=..

      The getTaggedObjects.sjs call retrieves records from that have the specified tag

      Parameters Required parameters
      object
      The object parameter that specifies the database table name
      tag
      The tag to match
      Optional parameters
      Limit the number of records to read in a call
      limit
      Limit the number of records returned to a specified count. The default is to return all matching records in chunks of 500 records.
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Examples
      Read all supporter records with tag bangarang!
      API_HOST/api/getTaggedObjects.sjs?object=supporter&tag=bangarang!

      Read all of the supporter records created using the signup page with key 6705

      API_HOST/api/getTaggedObjects.sjs?object=supporter&tag=signup:page6705

       

       

      Read all of the donation records tagged with FallGala

       

      API_HOST/api/getTaggedObjects.sjs?object=supporter&tag=FallGala

      getReport.sjs

      run a Salsa report, optionally providing parameters

      API_HOST/api/getReport.sjs?report_KEY=

      getReport.sjs takes a report_KEY and returns the result set of an existing salsa report

      Parameters Required parameters
      report_KEY
      The primary key in the report table for the report to run. This can generally be found in the address bar of the browser while editing the report.
      object
      The object parameter that specifies the database table name
      tag
      The tag to match
      Optional parameters
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      userVals=uNNNN

      Optional report parameters.

      Salsa reports have conditions that qualify and limit the records that are used in the output. For example, this is a typical start-date/end-date set:

      2015-04-10_1623.png

      When a condition is "User variable", Salsa presents a dialog page at the time that a report is run:

      2015-04-10_1602.png

      Submitting this page results in the parameters being passed to the report as uNNNN parameters:

      https://hq.salsalabs.com/salsa/hq/reports/report.jsp?report_KEY=64321&u55364=2015-01-01&u55365=2015-12-31

      In this URL, the optional parameters are

      &u55364
      Starting date (2015-01-01)
      &u55365
      Ending date (2015-12-31)

      The corresponding parameters to submit with getReport.sjs are:

      &userVals=u55364
      Starting date
      &userVals=u55365
      Ending date

      In order to pass parameters to a report using getReport.sjs, you'll need to run the report at least once to capture the parameter names and to learn the correct format for their values. See the examples for a sample call to retrieve a Salsa report.

      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON

      Examples

      Example URLs are split into lines to aid legibility.

      Run the report with key 2143. No parameters are required.
      API_HOST/runReport.sjs
      ?xml
      &report_KEY=2143
      

      Returns:

      <?xml version="1.0"?>
      <data organization_KEY="8564">
        <report>
          <row>
            <donation_KEY>1228989</donation_KEY>
            <Donorfirstname/>
            <Donorlastname/>
            <Donationamount>2.50</Donationamount>
            <InHonorName>honorof</InHonorName>
          </row>
          <row>
            <donation_KEY>1252218</donation_KEY>
            <Donorfirstname/>
            <Donorlastname/>
            <Donationamount>7.00</Donationamount>
            <InHonorName>fred</InHonorName>
          </row>
        </report>
      </data>
      
      Run report with key 64321 to get total donations by month for 2015
      API_HOST/runReport.sjs
      ?xml
      &report_KEY=64321
      &userVals=u55364=2015-01-01
      &userVals=u55365=2015-12-31
      

      Returns:

      <?xml version="1.0"?>
      <data organization_KEY="8564">
        <report>
          <row>
            <Month>2015-01</Month>
            <Total>154.00</Total>
          </row>
        </report>
      </data>
      

      /save

      save or update records in the database

      API_HOST/save?object=tablename&key=&fieldname=value...

      Summary

      • The /save API call is used to save records to the Salsa database.
      • The /save API call is used to update records in the Salsa database.
      • The /save API call requires authentication before it can be used. There is an exception...
      • The/save API call does not require authentication when it's used in a signup form on a website.

      Details

      Both inserts and updates are done by using a /save call. If there is a key parameter in the /save call, then Salsa attempts to update the record with a primary key of the key value. If the key parameter is not provided to /save, or if the key value is not a valid primary key, then Salsa automatically creates a new record.

      There is an exception. A /save to the supporter table uses three fields to determine if a supporter record exists:

      • uid
      • supporter_KEY (primary key for the supporter table)
      • Email

      If any of these fields match an existing record, then the values in /save are used to update the matched record. The fields are checked in the order shown, and the first field match determines the record to use. If no supporter records match, then a new record is created.

      Parameters

      Parameters are used in the /save call to specify

      • the database table to update,
      • the primary key for the record to be updated,
      • the data to be stored in the record, and
      • a method to link the record to records in other database tables.
      Required parameters
      object

      The object parameter specifies the database table name.

      Please note that some fields in some tables have restrictions and reservations, and may not behave the way that you might expect. You will want to peruse the database table layouts in this section of the documentation to learn abut the field restrictions and reservations that apply to the table to which your application is writing.

      fieldName=value

      Specify a field namein the object database table and the value that will be stored in it. Many fieldname=value parameters can be used to change or save multiple fields in the record. Here are some items that you'll need to know:

      • Field names are case sensitive. "Email" is correct, "email", "EMAIL" or "EmAiL" are wrong.

      • Field names are Camel-cased if they are fields in the object database table.

      • Lower-case names are custom fields, with one exception...

      • The "amount" field in the donation table is lower-case. -- "amount" is correct, "Amount", "AMOUNT" or "amOUNT" are wrong.

      Optional parameters
      key

      The key parameter is used to specify the primary key in object where the record will be saved. There are three valid forms of the key parameter.

      key=0 (zero)

      When a key is zero, Salsa generally creates a new record. The exception to this behavior is when a supporter record is being saved. Salsa may determine that the contents should be used to update an existing record instead.

      key=NUMBER

      When the value provided in a key parameter is a number, then Salsa attempts to update the record with a primary key of NUMBER. If the provided number does not resolve to a record in object, then Salsa returns an error result.

      When NUMBER is the primary key for a record, then Salsa uses the fieldname=value parameters to modify the record. If fieldname is not a valid field for object, then Salsa ignores it. Otherwise, the value of the field in the selected record is changed.

      Salsa writes the record to the database when all fields are processed. Please note that Salsa returns both success and error indications that need to be handled by your application.

      (key parameter not provided)

      If a key parameter is not specified, then Salsa uses the same logic as in the key=0 case.

      The link parameter contains the table name for the non-object table in the many-to-many relationship. For example, "groups".

      The linkKey parameter contains the primary key of the non-object table. Use a value value of zero in the linkKey parameter to indicate that a new record is being written.

      email_trigger_KEYS
      A comma-separated list of one or more autoresponse_KEYs. Salsa will send the autoresponse(s) to the newly added supporter after the supporter record is saved to disk. Click here to learn more about autoresponses.
      xml

      Set the returned format to XML

      json

      Set the returned format to JSON

      Recommended parameters

      key

      The key parameter is the primary key for a record and is highly recommended to clearly define how Salsa should treat the field data.

      Salsa recommends choosing one of these output format parameters:

      xml

      Set the returned format to XML

      json

      Set the returned format to JSON

      Examples

      Examples are split into lines to aid legibility. They are actually reaaally long URLs when they are submitted.

      Save a record to the database for Fred Flintstone (typos on purpose). Send autoresponses with keys 12345 and 12346.
      API_HOST/save
      ?xml
      &object=supporter
      &Email=fred@flint.stone
      &First_Name=Ferd
      &Last_Name=FlintSton
      &email_trigger_KEYS=12345,12346

      Returns:

      <?xml version="1.0"?>
          <data><success object="supporter" key="56295982">Modified entry 56295982</success>
      </data>
      Change the first name to "Fred" for the record with email fred@flint.stone and return the results in JSON.
      API_HOST/save
      ?json
      &object=supporter
      &Email=fred@flint.stone
      &First_Name=Fred

      Returns:

      [{"object":"supporter","key":"56295982","result":"success","messages":[]}]
      Change the last name to "Flintstone" and add an address for supporter key 56295982
      API_HOST/save
      ?xml
      &object=supporter
      &key=56295982
      &Last_Name=Flintstone
      &Street=301 Cobblestone Lane
      &City=Bedrock

      Returns:

      [{"object":"supporter","key":"56295982","result":"success","messages":[]}]
      Add Fred Flinstone to the following groups
      • "Drives to Work", groups_KEY=123456
      • "Heavy equipment", groups_KEY=123654
      • "Likes quitting time", groups_KEY=123789
      API_HOST/save
      ?xml
      &object=supporter
      &key=56295982
      &link=groups&linkKey=123456
      &link=groups&linkKey=12e654
      &link=groups&linkKey=123789

      Returns:

      <?xml version="1.0"?>
          <data><success object="supporter" key="56295982">Modified entry 56295982</success>
      </data>

      tagObject.sjs

      mark a database record with the specified tag

      API_HOST/api/tagObject.sjs?object=tablename&key=...&tag=..

      The tagObject.sjs call adds the specified tag to the tablename record with primary key key

      Parameters Required parameters
      object
      The object parameter that specifies the database table name
      key
      The key parameter is the primary key for a record.
      tag
      Thetagwith which to mark the record.
      Optional parameters
      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Recommended parameters

      Salsa recommends choosing one of these output format parameters:

      xml
      Set the returned format to XML
      json
      Set the returned format to JSON
      Examples
      Tag the supporter with supporter_KEY 123456 with the bangarang tag

      API_HOST/api/tagObject.sjs?object=supporter&key=123456&tag=bangarang!

      Tag the donation with key 99443 with the bangarang tag

      API_HOST/api/tagObject.sjs?object=donation&key=99443&tag=bangarang!

      Parameters

      the parameters used by API calls

      Key

      The key parameter is used to specify that an API call is used for only a single record. The key value is the primary key for the record to act on. Primary keys in Salsa are named table_KEY, where table is the database table name. Some examples:

      • supporter_KEY
      • donation_KEY
      • supporter_action_KEY

      Object

      The object parameter is a required parameter for all API calls. It specifies the database table to use for the call. Here is a list of the most commonly used database tables

      supporter

      The supporter table contains all of the information that Salsa stores about an individual supporter. A record contains both the standard fields (camel-cased field names) and the custom fields (lower-case field name). The suporter table can be viewed as the center of the Salsa data schema, with one-to-one links to some tables and one-to-many links to others

      donation

      Each donation record contains the information about a single donation. There is a one-to-many relationship between a supporter and donations. Note that there is no call in the Salsa API to submit a donation for processing.

      Note:There's not a mechanism in the API to submit a donatio for processing. Adding a record to the donation table simply adds a record.

      Notes about the object parameter
      • Most database names are singular (supporter, donation, action, etc)
      • The "groups" table is the only table that has a plural name.
      • The object parameter is case-sensitive. "supporter" and "donation" are correct. "Supporter" and "DONATION" are not correct.
      • Theobject parameter can be repeated to save more than one record with a single save.. Click here to learn more.

      Condition

      Conditions are used to restrict the records returned from an API call by the contents of the records being retrieved. If a condition is true for a record, then the record is returned.

      More than one condition can be provided for each API call. When there are more than one condition, then a record is returned if all of the conditions are true. The conditions can be thought of as being AND-ed together. Note that there is not an OR operator for conditions.

      A condition has the general form of

      &condition=field_name OPERATOR value

      (Spaces are provided for illustration and should not appear in the condition query.)

      Where
      field_name

      a database field name to use for comparison.

      OPERATOR

      The comparision operation between the field_name and the value

      value

      The value to compare. Some operations are unary and do require a value.

      Conditions apply to these API calls:

      Condition Parameters

      field_name

      The field_name parameter is the name of one of the fields in the table whose name appears in the object parameter for an API call. The field names and types are listed in the table schemas for Salsa tables. You can find schemas for the most common tables here. Field_names are formatted based on how they are used.

      Generic format

      The generic format of a field_name is

      table_name.field_name

      where table_name. can be optional.

      Single table format

      The bulk of Salsa's API calls operate on a single database table. In these calls, the table_name and .(dot) are left off, and the format of a field_name is

      field_name

      .

      Multi-table format

      The getLeftJoin.sjs call requires that field_names in comparisions have the full generic format. Salsa can use the same field name in more tha one table, and the table_name is required to disambiguate which field to use for comparison. For example, joining the supporter table to the donation table duplicates many field names. In order to compare against the Email field in the supporter table, the condition would look like this:

      &condition=supporter.Email="bogus@email.address"
      Note:
      • Database field_names have camel-cased names. For example
        • First_Name
        • Last_Name
        • Email
        • Zip
      • Custom field_names are all lower_case, and words are separated by an under bar. For example
        • membership_level
        • membership_type_code
        • dietary_choices_
        • fees___where applicable
      • Field_names are case-sensitive. Email is not the same field as email.
      • >In rare cases, database field_namesamount in the donation table). IN this case, amount is correct, Amount is not.

      OPERATION

      Specifies the type of comparision to do.

      =

      the content of field_name is equal to value. For example

      • First_Name=Judy
      • Date_Created=2015-09-03
      • amount=50
      • amount=12.34
      • true_or_false=1
      <

      the content of field_name is less than value

      >

      the content of field_name is greater than value

      <=

      the content of field_name is less than or equal to value

      >=

      the content of field_name is greater than or equal value

      IS EMPTY or %20IS%20EMPTY.

      the field value has a length of zero or is aYes/No field with a value of null or false. Note that the value is not needed. For example

      • First_Name IS EMPTY
      • First_Name%20IS%20EMPTY
      IS NOT EMPTYor %20IS%20NOT%20EMPTY

      the field value does not have a length of zero. Note that the value is not needed. For example

      • First_Name IS NOT EMPTY
      • First_Name%20IS%20NOT%20EMPTY
      IN or %20IN%20

      the field value is in a list of comma-delimited values in the value. For example

      • &condition=First_Name IN Bob,Ted,Carol,Alice,Rover
      • &condition=membership_level%20IN%20Gold,Silver,Tin
      NOT IN or %20NOT%20IN%20

      the field value is not in a list of comma-delimited values in the value. For example

      • &condition=First_Name NOT IN Fred,Barney,BamBam
      • &condition=membership_level%20NOT%20IN%20Platinum
      LIKE or LIKE or %20LIKE%20

      The field value matches a pattern. The pattern may be an exact match (for example "Bob") or it may contain wild card characters.

      Salsa uses the percent sign ( %) from MySQL as the wild card. Note that the percent sign must be encoded as %25 if you are working in a browser window. and before the URL is submitted via an application. Here are some examples:

      Find names that start with "A"
      &condition=FirstName LIKE A%25
              
      Find donations in December
      &condition=Date_CreatedLIKE%25-12-%25
              
      Last names that end in "son"
      &condition=Last_Name%20LIKE%20%25son
              

      Value

      The value parameter provides the value that's compared against the value in the field_name field in the record. The value can be any text or number. The value cannot be another field. The value should not contain the following characters. If you must have them, then escape them as shown:

      • apostrophe - &apos;
      • quote - &quot;
      • less than - &lt;
      • greater than - &gt;

      These operators must have a value:

      • equals
      • not equals
      • less than
      • greater than
      • less than or equal
      • greater than or equal
      • IN
      • NOT IN

      These operators must not have a value:

      • IS EMPTY
      • IS NOT EMPTY

      Fields in Salsa have different types, and values in comparisons need to be the same type. Please use this page as a guide for the correct datatypes and possible values.


      Include

      Summary

      The include parameter enumerates the fields to return in each record.

      Details

      The orderBy parameter is a comma-separated list of field names. Salsa returns a record from the database that contains the primary key for the and the values for each of the field names in the list.

      Examples
      &orderBy=Email
      [{"supporter_KEY":"55484467","Email":"Abe.Henson@barnes.barnes","key":"55484467","object":"supporter"},
      {"supporter_KEY":"56014127","Email":"able@able.able","key":"56014127","object":"supporter"},
      {"supporter_KEY":"55484523","Email":"Adelaida.Blanchard@hall.hall","key":"55484523","object":"supporter"},
      {"supporter_KEY":"55911295","Email":"chuck@chuck.chuck","key":"55911295","object":"supporter"}]
      &orderBy=First_Name,Last_Name,donation_KEY,amount
      [{"First_Name": "Abercrombie", "Last_Name": "Chuzwhizzle", "amount": "35.00", "key": "1238098", "object": "donation"},
      {"First_Name": "Able", "Last_Name": "Able", "amount": "1.25", "key": "1229214", "object": "donation"},
      {"First_Name": "Able", "Last_Name": "Able", "amount": "3.75", "key": "1229215", "object": "donation"},
      {"First_Name": "able", "Last_Name": "baker", "amount": "", "key": "1252052", "object": "donation"},
      {"First_Name": "able", "Last_Name": "baker", "amount": "", "key": "1252055", "object": "donation"},
      {"First_Name": "able", "Last_Name": "baker2", "amount": "", "key": "1252054", "object": "donation"},
      {"First_Name": "Abner", "Last_Name": "Blankwith", "amount": "6.25", "key": "1243843", "object": "donation"},
      {"First_Name": "Adam", "Last_Name": "Rasmussen", "amount": "300.00", "key": "1321367", "object": "donation"}]
      &orderBy=groups_KEY
      [{"supporter_groups_KEY":"413523247","supporter_KEY":"56160369","key":"413523247","object":"supporter_groups"},
      {"supporter_groups_KEY":"413523263","supporter_KEY":"56160371","key":"413523263","object":"supporter_groups"},
      {"supporter_groups_KEY":"363220885","supporter_KEY":"0","key":"363220885","object":"supporter_groups"}]
      Cautions

      Remember that you must disambiguate the field names if you are joining tables. For example, if you are joining the supporter and donation tables, the field names must specify eithersupporter or donation. For example,

      &orderBy=supporter.Last_Name,-supporter.First_Name,donation.amount

      Limit

      Summary

      The limit parameter tells Salsa the maximum number of records to return. The generic format for the limit parameter is

      &limit=[offset],count
      Details

      if offset is provided, then Salsa skips that number of records and begins reading. Note that Salsa's record counter is zero-based, so the first record in a table is record zero. Skipping 100 records will start reading on a record with offset of 100.

      Salsa attempts to read all count records. Here are the possible outcomes:

      • If the table is empty, then an empty array is returned. Responses in XML return a count field of zero.
      • If less than count records are available,
      • If the number of available records is greater than or equal to count, then Salsa reads count records but not more than 500 records. Responses in XML return count countfield.

      In order ready more than 500 records, then multiple reads need to be done. Each read will return 500 records as long as there are at least 500 records avialable. The last logical read will return a number less than 500. That will be your indication that the end of the table has been reached and that there are no more records available.

      Attempting to read past the end of the table returns an empty array. Responses in XML return zero in the countfield.

      Usage

      A limit can appear in all API calls that return more than one record:

      • getActions.sjs
      • getCount.sjs
      • getCounts.sjs
      • getLeftJoin.sjs
      • getObjects.sjs
      • getTaggedObjects.sjs

      A limit parameter is invalid in getObject.sjs because it only returns one record.

      Metacode

      Here is some metacode to demonstrate how to read more than 500 records from Salsa:

      offset = 0;
      do
      results = getObjects.sjs object=supporter, count=500
      Do something with the records
      offset = offset + results.count
      while results.count == 500
      Examples
      Read up to 500 records from the supporter record
      API_HOST/api/getObjects.sjs?object=supporter
      Read the most recent 5 actions taken by a supporter (broken down to aid legibility)
      API_HOST/api/getLeftJoin.sjs?json
      &object=supporter(supporter_KEY)supporter_action(action_KEY)action&condition=supporter_KEY=12345
      &include=action.Title
      &limit=5
      &orderBy=-action.action_KEY
      Read the first 15 actions taken by a supporter (broken down to aid legibility)
      API_HOST/api/getLeftJoin.sjs?json
      &object=supporter(supporter_KEY)supporter_action(action_KEY)action&condition=supporter_KEY=12345
      &include=action.Title
      &limit=15
      &orderBy=action.action_KEY
      Read 113 records starting at offset 2534 from the supporter_action table
      API_HOST/api/getObjects.sjs?object=supporter_action&limit=2534,113

      OrderBy

      Summary

      The orderBy parameter sorts the returned records by field value. Records can be sorted by any combination of fields in ascending or descending order.

      Details

      The orderBy parameter is composed of comma separated field names. If a minus sign (-) appears before the field name, then records ae sorted by the field value in descending order. The default is to sort in ascending order

      Examples
      Sort a list of supporter records in ascending order on the Last_Name and First_Name fields.
      &orderBy=First_Name,-membership
      Sort a list of supporter records in ascending order on the Zip field and in descending order on the First_Name field.
       &orderBy=-Zip,First_Name

      XML

      API_HOST/api/anyAPICall.sjs?xml&object=...

      Use &xml or &xml=true in any Salsa API call to return output in XML. If neither &xml nor &json is provided, then the output is returned as XML.

      Example
      Use &xml to return the results in XML
      <data organization_KEY="8564">
          <supporter_groups>
              <item>
                  <supporter_groups_KEY>413523247</supporter_groups_KEY>
                  <supporter_KEY>56160369</supporter_KEY>
                  <key>413523247</key>
                  <object>supporter_groups</object>
              </item>
              <item>
                  <supporter_groups_KEY>363220885</supporter_groups_KEY>
                  <supporter_KEY>0</supporter_KEY>
                  <key>363220885</key>
                  <object>supporter_groups</object>
              </item>
              <count>2</count>
          </supporter_groups>
      </data>

      JSON

      API_HOST/api/anyAPICall.sjs?json&object=...

      Use &json or &json=true in any Salsa API call to return output in JSON. If neither &xml nor &json is provided, then the output is returned as XML.

      Example
      Use &json to return the results in JSON
      [{"supporter_groups_KEY":"413523247","supporter_KEY":"56160369","key":"413523247","object":"supporter_groups"},
      {"supporter_groups_KEY":"363220885","supporter_KEY":"0","key":"363220885","object":"supporter_groups"}]
      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request

      Comments

      0 comments

      Please sign in to leave a comment.