Resource API

Resource API

What is an API?

Although there are a variety of ways to get data in and out of iCarol on a one-time basis, we also offer a method that significantly increases your options: the iCarol Application Programming Interface (API).
With this API, you can access your live iCarol data in ways never before possible. 
Here are some examples of what you could have programmers create, using the iCarol API:
  1. Mobile apps for iPhone, iPad, Android and other devices to let members of the public find nearby services.
  2. Live links to third-party software systems, like Homeless Shelter Management and Donor Management systems, that need to exchange real-time information with iCarol.
  3. Custom-built websites that let the public search and view Resource data. Currently, iCarol offers this feature with the standard iCarol Public Resource Directory, but with the iCarol API, your programmers will have lots more presentation options. Custom websites could even be targeted to certain sub-populations, like military veterans, caregivers, immigrants and so on. Your programmers could perhaps even use the API to help improve your search engine rankings.
  4. Custom resource exports in formats not currently provided in iCarol.

What is an Application Programming Interface (API)?

An API allows electronic systems to interact with each other without the need for the direct human intervention. That is, with an API no person needs to direct traffic between two systems, say via a website or other screen – the systems just talk directly to each other behind the scenes. In this way, the data that resides in the main system can be searched, retrieved and even modified by other authorized computer systems connecting to it. As the API’s publisher, iCarol can share the technical specifications and related documentation that would allow third party developers to access and use the iCarol API with other computer systems. We secure it in several ways, ensuring that only authorized computer systems can use the API, and that the data they can “see” is carefully controlled.

iCarol Resource API Service Overview

Common Search Implementation Design

There are many ways to use the Resource API to support your collaborations, partnerships, external applications, and websites. One common design is to first Search for resource records using specific criteria, 
display search results to users, then, based on a user action, request details for that record using the Get By ID method.

It is not uncommon for developers to use additional services for locations, to cache Resource Records, store copies of Resource Records, create their own request logs, or other utilities to support their application and design requirements. 

The below workflow diagram shows common steps:


Common Bi-Directional Updating Implementation Design

Based on permissions and settings on the Resource API key, API consumers may be able to create new resource records, as well as update and/or delete existing resource records.
For each Resource API key configured, iCarol Admins may enable the following settings:
  1. Action Type Permissions that grant access for the API consumer to Create, Update and/or Delete records
  2. Access Type Permissions control if the API consumer can perform actions for Any Record, Records with Guest Editing Permissions, or API editing permissions.
  3. Processing Permissions that control if the request will be automatically applied or if a Resource Editor must review and accept changes
The below workflow diagram shows common steps:


Limiting access to Resource Records based on Filters

When your organization has subscribed to the Resource API, you can choose per key to enable additional filters to limit the access of those using the key to the Resources they should have access to. For example, you may want to only allow a Resource API key user to Resource records with a specific custom field choice identifying their partnership, or to specific 211 Taxonomy codes. The following filters can be enabled and configured for each Resource API key:

Custom Field Filters

Limit an API Key to only resources, which are identified using a custom resource field. For example, records could be limited to just those which are identified as offering “Spanish” services, that serve “Youth”, or a named special project. Custom fields and answer choices are managed directly in iCarol by iCarol Administrators, and can be assigned to API keys from the API Key Management page.
Note: Make sure the custom field you wish to filter by doesn't have the setting enabled 'Only visible to resource editors'. Having this setting selected prevents the custom fields from being used to filter API records. 

211 Taxonomy Assignment Filters

Limit an API key to only resources with one or more 211 Taxonomy terms assigned. This allows resource editors to refine the resource records available to each API key based on how records are categorized and 
indexed instead of or in addition to custom field filters. For example, 211 Taxonomy could be used to categorize Programs and Services that offer various emergency and ongoing food assistance services, for an 
API key that focuses on food-related services. 

When adding 211 Taxonomy terms, administrators can choose to “Include All Child Terms,” which allows filter terms to be included at higher levels in the 211 Taxonomy. When adding multiple 211 Taxonomy terms, 
any resource with at least one (1) of the terms assigned as filters will be included in the results.
When using Custom Field Filters or 211 Taxonomy Filters, consider enabling the “Include Related Resources” setting. This setting will allow related records for those in filtered search results to also be available to the API key. For example, since 211 Taxonomy Terms are often only assigned to Program records, by enabling the “Include Related Resources” setting, the Programs-related parent Agency, Site and ProgramAtSite would also be available.

Include Private/Confidential Information

Administrators may also choose to grant access to private/confidential information in their Resource records to API consumers. Private/Confidential information is identified with a Boolean flag on the Resource Record field. Fields that support Private/Confidential settings include:
  1. Contact details for Main Contacts and Directors or Senior Administrators. Including the Name, Title, Phone Number and Email Address for the contact.)
  2. Phone number details. Including named phone numbers (e.g. Toll-Free, Hotline, Business Line, etc.) and numbered phone number fields.
  3. Address Information for Physical Addresses and Mailing Addresses. Including Address Line 1 and 2, Towns/Districts, Community, City, County, State, Country, Zip/Postal Code.

How to enable Filters

After an API Key has been created for your organization, you can modify your filter by completing the following steps:
  1. As an Admin level user, click Admin tools from your left side menu
  2. Click the API tab at the top of the page
  3. From the 'Select API Key' drop-down list, choose your desired API
  4. From the filter settings, enable/disable desired filters
  5. Click the "Save" button

Securing the iCarol API with “keys”

To be able to access any data via the iCarol API, you’d need to purchase at least one “API Key.” Each API Key will specify strict permissions regarding your data. With the purchase of an API Key:
  1. You’d be sure that the computer software using an API Key gets just the data you intend and cannot manipulate your data in unauthorized ways.
  2. You’d see reports on activity generated per API Key.
  3. Since each API Key’s ongoing costs would be associated with its usage, you could allocate the costs of the API Keys to whoever is paying for the capability (e.g. a specific funder, partner, or internal department).
  4. You’d be able to turn off an API Key at any time, which terminates access to the iCarol API for any and all computer systems using it.
Once you’ve given an API Key to a software developer, you should assume from that point on they (and any software they create) have access to your data in iCarol as specified by the API Key’s capabilities. For that reason, having the appropriate number of individual API keys, as well as taking care to define to the permissions detailed for each one, offers you granular control, reporting, and termination capacities over those computer systems using them.

For example, you might purchase an API Key that is Read Only for your Resource database in iCarol, and give that to a third party who is building an iPhone app for you. You might purchase a second API Key that is also Read and Write for your Resource database, and give that one to the folks building a third-party database where resources are also being updated and the updates are pushed back into iCarol.

Additional Security using IP Whitelisting

Internet Protocol (IP) Whitelisting
The iCarol Resource API supports Internet Protocol (IP) Whitelisting, which works along the Access Token to enhance the security of the customer's API. By whitelisted IP addresses in the API’s settings, iCarol admins can further limit the external applications that can successfully make requests to their API.

How long does it take to enable the iCarol API?

On our side turning it on is relatively quick. The time really comes into play when the developers begin implementing the web page or site to display the information. There’s a lot of variability in the implementation timeline, depending upon what they want to do, and their skill level. Oftentimes we have multiple conference calls with them to work through their questions. 

How to locate API Keys

If your organization already has an API configured, you can access the key yourself to provide to whoever you need, by completing the following steps:
  1. As an Admin level user, click Admin tools from your left side menu
  2. Click the API tab at the top of the page
  3. From the Select API Key drop-down list, choose your desired API
  4. The page will reload, and your API key will appear for you to copy, and provide to whoever you need
Note, this feature may have an additional cost associated with it. If your organization is interested in enabling this feature, then a designated Support Contact from your organization can go to 'Help' in the left side menu and submit a case to request more information.

    • Related Articles

    • Training Webinars: iCarol Resource and Contact Record API

      During this training participants will learn: What is an API? What can an API do? How to setup an iCarol Resource or Contact Record API What are some real use cases with the iCarol Resource API? What are some real use cases with the iCarol Contact ...

    • Yanzio Integration for Resource Evaluations

      What is the Yanzio Integration? Yanzio.ai is a cloud-based service that uses artificial intelligence to build capacity and support the information and referral community. Yanzio and iCarol have worked together to offer iCarol customers a free trial ...

    • Contact Record API

      What is the Contact Record API? The Contact Record (Call Report) API allows you to seamlessly share contact record data collected within iCarol with external applications and allows those applications to send information back to iCarol to update ...

    • Training Webinar: Sharing your Data Outside of iCarol

      During this training participants will learn: Manual Exports Standard Exports Export Template Builder Scheduled Exports Standard Exports Export Template Builder API Contact Record Resource

    • Configuring Resource Search Result Fields

      Resource Search Result Fields Resource fields included in search results by default, if values exist in the records fields include: Record Name Alternative Name Record Type From: Parent Record Name (if the record is a Program or Site) Distance from ...