API Post

1. Above the list of existing API Posts, click + New button.

2. A New API Post pop-up window is displayed. In the Name field, enter a name for the new API Post.

3. From the Data Source drop-down menu, select the source table into which this API Post will load data.

Note: You can never modify this source table after the API Post is created.

4. Click save new item. The Workspace is refreshed to show a blank API Post details screen, where you can configure the details of the API Post.   

1. Select a mapping option:

Simple

The Simple mapping option allows you to manually select one or more fields on the API Post source table.

read more

1. Select the Simple tab.

2. From the drop-down menu, select one of the following options that controls how the system handles the import records:

   • Update or Create All Records: Select this option if you want the import process to create new records, and update existing records.

   • Only Update Existing Records: Select this option if you want the import process to only update existing records (new records are ignored).

   • Only Create New Records: Select this option if you want the import process to only create new records (updates to existing records are ignored).

3. The Available Fields list box displays all the fields on the API Post's source table. Select a field, then click the center "add" bar to add the field.

4. Repeat the above step as needed to add more fields to the API Post.

Advanced

The Advanced option lets you pick an existing Data Map to use when bringing data in through the Web Form. Data Maps provide more sophisticated import options.

read more

1. Select the Advanced tab.

2. In the Data Map field, either begin typing in the Data Map name, or click the browse button (magnifying glass icon) to browse for and select it. You can also create a new Data Map by clicking the new button (plus-sign icon). See Data Maps for more details.

3. Optionally, if you want to view the details of the Data Map after selecting it, click the jump-to button (green up-arrow icon). The system displays the Data Maps screen.  

If the API request message doesn't contain the Unique Identifier field for the destination Table, then you must use the Soft Match feature in order to successfully load the data. The Soft Match lets you match to the database using any fields with a Data Type of "Email," "Phone," "Twitter," or "Push Registration ID." For example, let's say the Unique Identifer on your "Recipient" table is "Member ID," but you don't have Member ID data available in your import file. You could instead select some other field, such as "Email Address," that contains unique data, and match on that instead.

If the soft-matched value in the request message matches an existing value in the database, then the platform will make the update to that record in the database. If the soft-matched value does not already exist in the database, the platform creates a "temporary" record. This temporary record can later be merged with a full record that contains the Unique Identifier.

If you're using the Soft Match feature, you still must add the Source Table's Unique Identifier field (or fields) to the API Post, even if you're not actually intending on providing the Unique ID fields on the inbound data. The Unique ID must be part of the API Post in order to save the API Post; you don't need to actually include this field (or fields) when you bring data into the system.  

Define a Soft Match

read more

1. In the Soft Match section, click the Select Fields tab. The Available Fields list box is populated with all of the mapped fields that can be used for soft matching.

2. Select a field in the Available Fields list box, then click the center Move bar. Optionally, you can use Shift + click or Control + click to select and move multiple fields. The selected field (or fields) is added to the Selected Fields list box. Repeat this step as needed to add more fields to the Soft Match. To remove a field from the Soft Match, click the X icon next to the field name within the Mapped Fields list box.

2. The Hierarchy Options drop-down menu is typically used if your account utilizes a multi-division setup, such as a Parent / Child database. Hierarchy Rules are a configuration feature set in the Parent system that determine which records from a given table a Child system can access. From this drop-down menu, select one of the following options:

   • Update Records in Current Customer Only: This option will load the data to the Parent system only.

   • Update Records in Current Customer and Children: This option will load the data to the Parent, and to any Child systems as well.

   • Custom Hierarchy Rule: This option allows you to select a custom Hierarchy Rule. If you select this option, the Hierarchy Rule field is displayed. To use an existing Hierarchy Rule, either begin typing in the Hierarchy Rule name, or click the browse button (magnifying glass icon) to browse for and select it. You can also create a new Hierarchy Rule by clicking the new button (plus-sign icon).  

3. If your account contains custom stored procedures, you can optionally run a stored procedure after the record in the API Post is processed. From the Post-Update drop-down menu, selected the desired custom stored procedure. 

4. If the Source Table contains Calculated Fields, you can optionally derive and populate those Calculated Fields upon receipt of an API request message. Click the "Run Calculated Fields" tab in the "Processing" section. The "Available Fields" list box is populated with all of the Calculated Fields in the source table. Select a field in this list box, then click the center "Move" bar. Optionally, you can use Shift + click or Control + click to select and move multiple fields. The selected field (or fields) is added to the "Selected Fields" list box. Repeat this step as needed to add more Calculated Fields. To remove a Calculated Field, click the "X" icon next to the field name within the "Selected Fields" list box

Note: If you run a Calculated Field as part of an API Post, the system derives and populates that field only for the record in the API request message. Conversely, if you set up a Calculated Field schedule, the system derives and populates the field for every record in the table (see Tables for more details).

5. Optionally, if you want your API request message to use the secured RESTful architecture, place a check mark next to "REST API Only." If you select this option, you must use the REST API endpoint, and use OAuth 2.0 authentication.

6. Optionally, if you want your API request message to trigger a campaign immediately, before loading the request data to the database, place a check mark next to "Triggering." If you leave this option unchecked, you can still use this API as a trigger mechanism, but the system will load the data to the database first, then deploy the campaign message. The combination of the above two check boxes is use to determine which API you want to use.

   • Both unchecked -- HTTP POST Load API or Sequential Data Load API

   • Both checked -- Email Campaign Trigger API

   • REST API Only checked / Triggering unchecked -- Standard Event Trigger API

7. If you want to capture and store records that encounter exceptions, place a check mark next to Import Exceptions (note: this is an optional feature that must be enabled within your account in order to be available for selection).

8. If you checked the Triggering check box, you have the option of selecting a Web Authentication. The Web Authentication is used to determine if the record in the API message is a new record, or an existing record. The platform will attempt to match the API message to the database using the field (or fields) in the Web Authentication. From the Authenticate drop-down menu, select the desired Web Authentication (see Web Authentications for more details).

9. Optionally check Sanitize Data Fields to encode all fields in the API Post. This feature is intended to prevent cross-site scripting (XSS) vulnerabilities in your API Post. If enabled, the platform will automatically encode all fields in the form. You can optionally choose to leave specific fields un-encoded by attaching the suffix " unsafe" (with a space) to the field name. For example: "email unsafe." 

Note: The Sanitize Data Fields option is enabled by default in all new API Posts created after release 21.10 (October 2021) of Missing variable reference. All API Posts created prior to this release will have this feature disabled by default. You can optionally enable the feature in older API Posts, or you can choose to encode specific fields by attacking the suffix " safe" (with a space) to the field name. For example: "email safe." Missing variable reference's best practice is to enable this feature, but please note that enabling the feature in older API Posts may cause changes to the format of field content, so be sure to test the API Post after enabling this feature.

10. In the Tool Ribbon, click Edit > Save.

1. In the Choose Notification Type drop-down menu, select the desired metric (or All Metrics). The Notification Settings pop-up window is displayed.

2. In the Notification Thresholds section, enter the desired threshold settings that will trigger the alert notification. You can enter one or both of the following rules. If you enter both rules, the notification will be triggered if at least one condition is met.

   • Percentage of batch: Enter the percentage of "invalid" records that will trigger the notification.

   • Number of rows: Enter the quantity of "invalid" records that will trigger the notification.

3. Email notification settings can optionally be saved as a template, which allows you to reuse those settings. In the Email Settings sections, you can either select an existing email notification template, or create a new template.

   • Existing Template: Selected the desired template from the Template drop-down menu.

Note: If you want to delete an existing Template, select it from the Template drop-down menu, then click delete.

• New Template: Enter the email subject line, "from" email address, and recipient email address (or multiple addresses). Enter a short message for the email notification. Optionally, if you want to save these email notifications settings, enter a name for the template in the "Save Template As" field.

4. If you want the system to send notifications after the parsing step, place a check mark next to "Parsing."

5. If you want the system to send notifications after the database update step, place a check mark next to "Update."

Note: You must check at least one of the above check boxes.

6. Click ok. the system adds the email notification to the Selected Notifications list. To view or edit the notification details, click the edit button (gear icon); the Notification Settings pop-up window is displayed. To delete a notification, click the delete button (X icon).

7. Repeat the above steps as needed to define the email notifications for additional metrics. Each selected metric is handled separately, and will generate its own email notification message.

8. In the Tool Ribbon, click Edit >Save.  

You can also define a confirmation page using the "cp" parameter. For example:

<input type="hidden" name="cp" value="http://www.cheetahdigital.com" />

1. Optionally, make any necessary changes to the success confirmation response message.

2. If you provided the confirmation page using the "cp" parameter , check the check box labeled, "Confirmation page URL indicated in form code via 'cp=' parameter." This check box instructs the platform to use the "cp" parameter value, and not to use anything provided above in step 1. Conversely, leave the check box unchecked to use the message you provided above in step 1.

3. In the Tool Ribbon, click Edit > Save.

If your API Post is finished, the next step is to publish it. See Publish an API Post below for more details on this process.

1. Optionally, in the Maximum entries per user field, enter the maximum number of times that a single recipient can submit this API Post. If a recipient surpasses this threshold, the system displays an error message.

2. Optionally, in the Maximum entries per form field, enter the maximum number of submissions allowable for this API Post, across all recipients. If the API Post surpasses this threshold, the system displays an error message.

Note: Be careful when testing API Post submissions, as the test submissions count toward both of the above thresholds. 

3. Optionally, to define a start schedule for the API Post, click the Start On toggle next to API Post Start Date, then enter the start date and start time. Optionally, to make the API Post available immediately after it's published, click the Start Immediately toggle.

Note: If using the schedule feature, when you publish your API Post, it won't yet be available until the schedule's start date. 

4. Optionally, to define an expiration schedule for the API Post, click the End On toggle next to API Post End Date, then enter the end date and end time. After the designated end date / time,  the system will return the Expiration message (described below). Optionally, to make the API Post run indefinitely, click the Run Indefinitely toggle.

5. In the Tool Ribbon, click Edit > Save.

If your API Post is finished, the next step is to publish it. See Publish an API Post below for more details on this process.

1. Optionally, in the Expiration field, enter the expiration message.

2. In the Tool Ribbon, click Edit > Save.

If your API Post is finished, the next step is to publish it. See Publish an API Post below for more details on this process.

1. Search for the desired item (see Search for an Item for more details).

2. Click on the item name. The main item screen is displayed and populated with the details of the selected item.

3. In the Tool Ribbon, click Edit > Save As. A Save as dialog box is displayed.

4. Enter a name for the new item.

5. By default, the new item will be saved in the same folder location as the base item. Optionally, click the magnifying glass icon to browse to and select a different folder location.

6. Click save a copy. The system creates a copy of the selected item.

To publish your API Post:

1. In the Tool Ribbon, click Edit > Save and Make Public.  

2. If you need the URL for the published API Post, click Tools > Generate URLs in the Functional Menu. Select a domain from the Domain drop-down menu. The Post URL field displays the final published URL.  Also, the system generates a Share Data URL. This URL contains a log of the last 10,000 records that were received through this API Post.

1. Search for the desired API Post (see Search for an Item for more details on the available search methods).

2. Click on the API Post name. The API Post screen is displayed and populated with the details of the selected API Post.

3. Optionally, to view detailed information about the API Post, click the API Post tab in the Tool Ribbon. The Item Details screen is displayed, showing who created the item, who modified it last, and what the last actions taken on the item were. On this screen, click Related Items in the Function Menu to see other items in the system that reference or utilize this API Post. When finished, click the Edit tab in the Tool Ribbon to return to the main edit screen.

4. Optionally, you can assign one or more tags to your API Post. To assign a tag, click on the Add tag field in the Edit section of the Tool Ribbon. The system displays a pop-up menu of all the existing tags. You can select one of these tags, or type in a new one and press Enter. You can repeat this process to add more tags. To remove a tag, click the X icon next to the tag label.  

5. Optionally, to rename the API Post, click Edit > Rename. A Rename Item dialog box is displayed. Enter a new name for the API Post, then click save new name.

6. To save your changes, click Edit > Save in the Tool Ribbon. Or, if you're ready to publish the revised API Post and make it available for use, clickEdit > Save and Make Public.

Note:  If you're using the Maximum submission counters for this API Post, republishing the API Post will reset all counters back to "0."

1. Search for the desired item (see Search for an Item for more details).

2. Click on the item name. The main item screen is displayed and populated with the details of the selected item.

3. In the Tool Ribbon, click Edit > Delete. A confirmation dialog box is displayed.

4. Click delete item to confirm the deletion.

Foldered items are moved to the Recycle Bin. Non-foldered items are permanently deleted.

Note: this sample code is intended for reference purposes only.

To view sample code for your API Post:

1. In the Function Menu, click Sample Code.

2. In the Select Sample Code drop-down menu, select the desired language. The large text field is populated with the sample code.

The following table lists the parameters that should be sent as part of the API request: