Some uses for this feature include:

1. As an iCarol client, I want to send submitted contact records in my iCarol system to an external dashboard for real-time reporting, like 211 Counts
   
2. As an iCarol client, I want to complete intake forms for specific services, for example, counselling, health follow-up, damage assessment, homeless shelter screening, mobile crisis dispatch, etc., and have that intake form automatically sent to the referred service, so they know to expect a help-seeker and have their information ready to go
   
3. As an iCarol client, I am contracted by another agency to provide services, for example, crisis support, EAP, counselling, etc., and the contracting agency wants to receive a copy of all submitted documentation related to their contacts
   
4. As an iCarol client, I send data to a partner or funder (e.g. STARS/SHIPS, Billable records to Health partner, etc.), and they wish to update the iCarol Contact Record with a status and external system ID when the record is processed
5. Integrated supported referral/closed-loop referral system where records are shared with a partner, and the partner can send additional information back
   
6. Integration for external messaging where the chat transcript is copied to iCarol
   

To get started with setting up this feature, provide iCarol Support with the following information: 

1. API Outbound Only or Allow Updates: specify if you would like your partners to be able to update Contact Records using the API or if you would like this to be an Outbound Only API, meaning you only send data to your partners using the API and they aren't able to update the Contact Record in iCarol using the API
   
2. Contact Record Version(s): provide the name of the contact record version(s) that are used to send data
   
3. Fields to Filter: if any field selections should be used as criteria to filter the contact records sent, include the name of the Category, Group, and Field. For example, if only call reports where 'Billable' is selected should be sent, then you must specify 'Contact Information (Category): Contact Type (Group) = Billable (Field)'. You can choose any number of fields to use as filters. Alternatively, you may wish to not filter the contact records and instead send all, regardless of field selections.
   
4. Your Webhook URL
   
5. (Optional) Provide Token/Credentials for Authentication
   
6. (Optional) Whitelist iCarol IP Addresses

To Update Existing Contact Record API:

1. Click Admin Tools in your left side menu, then select the API tab at the top of the page
   
2. Click the link to access the "API Key Management"
   
3. Choose the Contact Record API from the "Select API Key" drop-down list at the top of the page
   
4. On the right side of the page, update the "Contact Form Versions accessible by this API Key" or "Outbound API calls" settings and click "Save"

How Does The Contact Record API Work?

Important notes to consider about allowing updates with the Contact Record API:

1. There are no limits, permissions or validation on which field or records the API consumer can update/edit using the configured Contact Form assigned to the API connection, meaning is it possible that the API consumer could update any record created using the form, regardless of dispatch trigger fields
   
2. Changes made by the API are logged in the Contact Record Change History
   
3. At this time, this is an UPDATE method only, meaning new records cannot be created, and existing records cannot be deleted.
   

Contact Record API Dispatch Status

Important Notes:

1. The Dispatch Status only displays when using Report Version 5 Contact Forms
   
2. New dispatch attempts can also be triggered by editing and then submitting the Contact Record.
   

Contact Record API Dispatch Logs

How to export Standard Contact Record API Dispatch Logs:

1. Log in as an Admin, or a user with access to Contact Record exports
   
2. If you are an Admin, click on 'Admin Tools' from the left menu, then click the 'Tools' tab, then click 'Extract all of your data' in the 'Data Export' section.
   
3. If you are a non-Admin, click 'Data Exports' at the bottom of the Home page.
   
4. Under the 'Contact Records' section
   
1. Choose a timeframe
   
2. Select 'Standard Export'
   
3. Click the 'Include Dispatch API Log' check-box
   
4. Choose the Contact Form(s) to include
   
5. Click 'Export Contact Records per option above' button
   
5. Once the file has been generated, you will receive an email notification and the file will be downloadable from the 'Queued or ready for download' section.  Click the export to download it
   
6. In the zip file downloaded, open the file titled 'iCarolExport-[YourSystemName]-CallReportAPIDispatchLog-[Date]-[id].csv' 
   

How to export customized Contact Record API Dispatch Logs using the Export Builder:

1. Log in as an Admin
   
2. Click on 'Admin Tools' from the left menu
   
3. Click on the 'Tools' tab
   
4. Click on 'Template Editor' from the 'Data Export' section
   
1. Edit or Create a new Export Builder Bundle with Layouts, Fields and Mappings.  To include Contact Record API Dispatch Log data, choose this as a Content Type
   
5. If you are an Admin, click on 'Admin Tools' from the left menu, then click the 'Tools' tab, then click 'Extract all of your data in the 'Data Export' section
   
6. If you are a non-Admin, click 'Data Exports' at the bottom of the Home page
   
7. Under the 'Contact Records' section
   
1. Choose a timeframe
   
2. Select 'Template Export'
   
3. Choose the Bundle to export from the 'Export Template Bundle' drop-down menu
   
4. Click 'Export Contact Records per option above' button
   
8. Once the file has been generated, you will receive an email notification and the file will be downloadable from the 'Queued or ready for download' section.  Click the export to download it
   

Contact Record API Error Review

How to access the API Log and Review Page:

1. Log into iCarol as a Supervisor, Admin, or a user with permission to access this page
   
2. Click on 'Contacts' from the left hand menu
   
3. Click on 'API Error Review' at the bottom of the yellow menu box
   

      

1. Filter: using the drop-down menus at the top of the page, users can filter by Contact Form Version, the API Name, and, if sharing is enabled, the iCarol System name
   
2. Search: by id, date, and various fields
   
3. Choose how many error to show per page, and navigate pages
   
4. View a count of errors displayed
   
5. Sort error by column headers/titles
   
6. Select/unselect all, or an individual record
   
7. Retry single records by clicking 'Retry' on the right of each row
   
8. Retry all selected records by clicking 'Retry dispatch for selected records' from the bottom of the page

How to grant access to the API Error Review page to Standard users:

1. Log in as an Admin, or a user with access to managing Vols-Staff accounts
   
2. Click on 'Vols-Staff' from the left menu
   
3. Locate the name of the Vol-Staff person you would like to manage, and click their name
   
4. Click on the 'Admin' tab
   
5. Click on 'Advanced Security Settings'
   
6. In the 'Contact Records' section, check the box next to 'Can access Contact Record API Error Log Review page'
   
7. Click 'Save Settings' button

Note, this feature may have an additional cost associated with it. If your organization is interested in enabling this feature, have a designated Support Contact from your organization go to 'Help' in the left side menu and submit a ticket to request more information.