API: listOrganizations
  • 3 Minutes to read
  • Dark
    Light

API: listOrganizations

  • Dark
    Light

Article summary

  • Starting June 1, 2022, SmarterU will require all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
  • If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
  • Tags are required unless specified.

Description

The listOrganizations method retrieves organizations that meet the specified filters. 

Who Has Access

The following users have access to the listOrganizations method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>listOrganizations</Method>
   <Parameters>
      <Organization>
         <Page><![CDATA[]]></Page>
         <Filters>
            <OrganizationStatus><![CDATA[]]></OrganizationStatus>
            <CreatedDate>
              <CreatedDateFrom></CreatedDateFrom>
              <CreatedDateTo></CreatedDateTo>
            </CreatedDate>
            <ModifiedDate>
              <ModifiedDateFrom></ModifiedDateFrom>
              <ModifiedDateTo></ModifiedDateTo>
            </ModifiedDate>
          </Filters>
      </Organization>
   </Parameters>
</SmarterU>

Organization Tag Group

The Organization tag group is a container for organization filters. 

<Organization>
   <Page><![CDATA[]]></Page>
   <Filters>
      <OrganizationStatus><![CDATA[]]></OrganizationStatus>
      <CreatedDate>
         <CreatedDateFrom></CreatedDateFrom>
         <CreatedDateTo></CreatedDateTo>
      </CreatedDate>
      <ModifiedDate>
         <ModifiedDateFrom></ModifiedDateFrom>
         <ModifiedDateTo></ModifiedDateTo>
      </ModifiedDate>
   </Filters>
</Organization>

The Organization tag may contain the following.

Page (optional)

The page number to return. The default is 1 and each page returns 1000 records. For example, the following returns records 1001-2000.

<Page><![CDATA[2]]></Page>

Filters

A container for organization filters. Refer to Filters Tag Group.

Filters Tag Group

The Filters tag group is a container for organization filters.

<Filters>
   <OrganizationStatus><![CDATA[]]></OrganizationStatus>
   <CreatedDate>
      <CreatedDateFrom></CreatedDateFrom>
      <CreatedDateTo></CreatedDateTo>
   </CreatedDate>
   <ModifiedDate>
      <ModifiedDateFrom></ModifiedDateFrom>
      <ModifiedDateTo></ModifiedDateTo>
   </ModifiedDate>
</Filters>

The Filters tag may contain the following.

OrganizationStatus (optional)

The organization's status. Acceptable values are Active, Inactive, or All. The default is All

CreatedDate (optional)

A container for filtering organizations based on the date they were created. This tag contains the following. 

TagDescription

CreatedDateFrom

The first date to include in the created date range filter. 

CreatedDateTo

The last date to include in the created date range filter.

  • Dates should be in UTC and in the format dd-MMM-yyyy. 
  • Only one CreatedDate filter can be specified. 
  • If both a CreatedDate filter and a ModifiedDate filter are specified, the method will return all organizations that were created within the created date range OR modified within the modified date range. For example, if an organization was created within the created date range, but their modified date is outside the modified date range, the organization will be included.

ModifiedDate (optional)

A container for filtering organizations based on the date they were last updated. This tag contains the following. 

TagDescription

ModifiedDateFrom

The first date to include in the modified date range filter.

ModifiedDateTo

The last date to include in the modified date range filter.

  • Dates should be in UTC and in the format dd-MMM-yyyy.
  • Only one ModifiedDate filter can be specified. 
  • If both a CreatedDate filter and a ModifiedDate filter are specified, the method will return all organizations that were created within the created date range OR modified within the modified date range. For example, if an organization was created outside the created date range, but their modified date is within the modified date range, the organization will be included.

API Response XML Package

The API response XML package will always include a Result, Info, and Errors tag.

<SmarterU>
   <Result></Result>

   <Info>     
      <Organizations>
         <Organization>
            <ID><![CDATA[]]></ID>
            <Name><![CDATA[]]></Name>
            <OrganizationID/>
            <Created_Date><![CDATA[]]></Created_Date>
            <Modified_Date><![CDATA[]]></Modified_Date>
            <Status><![CDATA[]]></Status>
            <Email><![CDATA[]]></Email>
            <PhonePrimary><![CDATA[]]></PhonePrimary>
            <PhoneAlternate><![CDATA[]]></PhoneAlternate>
            <Fax><![CDATA[]]></Fax>
            <Address1><![CDATA[]]></Address1>
            <Address2><![CDATA[]]></Address2>
            <City><![CDATA[]]></City>
            <PostalCode><![CDATA[]]></PostalCode>
            <Province><![CDATA[]]></Province>
            <Country><![CDATA[]]></Country>
            <Website><![CDATA[]]></Website>
            <UserCount><![CDATA[]]></UserCount>
            <CustomFields>
               <CustomField>
                  <Name><![CDATA[]]></Name>
                  <Value><![CDATA[]]></Value>
               </CustomField>
            </CustomFields>
         </Organization>
      </Organizations>
   </Info>

   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

The Organizations tag is a container for the organizations returned by the listOrganizations method. Each organization is contained in an Organization tag and may contain the following.

ID

The organization's system-generated identifier.

Name

The organization's name.

OrganizationID

The organization's user-specified identifier.

Created_Date

The UTC date the organization was created.

Modified_Date

The UTC date the organization was last updated.

Status

The organization's status.

Email

The organization's email address.

PhonePrimary

The organization's primary phone number.

PhoneAlternate

The organization's alternate phone number.

Fax

The organization's fax number.

Address1

The first line of the organization's street address.

Address2

The second line of the organization's street address.

City

The city of the organization's street address.

PostalCode

The postal code of the organization's street address.

Province

The region (e.g., state, province, etc...) of the organization's street address.

Country

The country of the organization's street address.

Website

The organization's website.

UserCount

The number of users associated with the organization.

CustomFields

A container for the custom organization fields. Each custom organization field is contained in a CustomField tag and may contain the following.

TagDescription

Name

The custom organization field's name.

Value

The value assigned to the custom organization field. 

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>
   <Info>

      <Organizations>
         <Organization>
            <ID>19852</ID>
            <Name><![CDATA[Rhizome Unlimited]]></Name>
            <OrganizationID/>
            <Created_Date><![CDATA[2018-03-21 20:17:34.39]]></Created_Date>
            <Modified_Date><![CDATA[2019-07-23 17:48:46.893]]></Modified_Date>
            <Status><![CDATA[Active]]></Status>
            <Email><![CDATA[pierre.bellamy@rhizomeunlimited.com]]></Email>
            <PhonePrimary><![CDATA[703-432-2093]]></PhonePrimary>
            <PhoneAlternate><![CDATA[703-432-2090]]></PhoneAlternate>
            <Fax><![CDATA[703-432-2100]]></Fax>
            <Address1><![CDATA[93200 Rhizome Boulevard]]></Address1>
            <Address2><![CDATA[Suite 100]]></Address2>
            <City><![CDATA[New York]]></City>
            <PostalCode><![CDATA[10020]]></PostalCode>
            <Province><![CDATA[New York]]></Province>
            <Country><![CDATA[United States]]></Country>
            <Website><![CDATA[http://rhizomeunlimited.com]]></Website>
            <UserCount>1</UserCount>
            <CustomFields>
               <CustomField type="String">
                  <Name><![CDATA[Fina Partner Level]]></Name>
                  <Value><![CDATA[Platinum]]></Value>
               </CustomField>
               <CustomField type="Date">
                  <Name><![CDATA[Fina Partnership Date]]></Name>
                  <Value><![CDATA[03-Jun-2009]]></Value>
               </CustomField>
            </CustomFields>
         </Organization>
      </Organizations>
   </Info>

   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

Error Codes

Error CodeMessage
LO:01
The page number provided is not valid.
LO:02
The organization status provided is not invalid.
LO:03
The required permissions are not met to call the listOrganizations method.
LO:04
The created date provided is not valid.
LO:05
The modified date provided is not valid.

Was this article helpful?