API Post

To create a new 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.   

The Data Options section is used to define a Form that tells the system how to save the data into the database. It can be useful to create multiple Forms, even if those Forms are saving similar data. Different Forms can be used as triggers for different purposes, or as a method to logically separate data based on different data sources.

1. Select a mapping option:

SimpleSimple

AdvancedAdvanced

 

 

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 MatchDefine a Soft Match

 

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 Engage+. 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." Marigold'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.

The Confirmation section contains a default response message that gets generated upon successful receipt and processing of your API request. This default response message contains a Status value of "SUCCESS."

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.

The API Post Schedule section provides several options for disabling, or expiring, this API Post, either based on the number of submissions received, or based on a schedule.  

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.

If you're using the API Post expiration schedule described above, the Expiration section lets you define the response message that gets submitted in the event that the API Post is accessed after its expired.

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.

To copy an existing item to use as the basis for a new item:

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.

After you've created the API Post to your satisfaction, you must publish it to make it accessible.  

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 a "Share Data" URL. This URL contains a log of the last 10,000 records that were received through this API Post.

To view or edit an existing 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, click Edit > 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."

To delete an item:

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.

Messaging will generate sample HTML, XML, and C# code based on the API Post parameters that you entered above.

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:

Parameter	Name	Definition / Example	Example	Required
	Post URL	The URL to which the data should be posted	http://forms.client-domain.com/ats/post.aspx	Yes
cr	Customer ID	Each client is given a unique Customer ID, which identifies which client database to update.	123	Yes
fm	Form ID	The Form ID (also called the Object Reference ID) is the unique identifier for this particular Form; this value can be found by clicking the API POST tab in the Tool Ribbon.	37	Yes
cn	Campaign ID	When a campaign is sent, it generates a Campaign ID, which can be used to relate a Form post to a campaign for reporting purposes ( this is not necessary if Message ID is provided)	4567890	No
mg	Message ID	When campaigns are sent, each recipient receives a Message ID for that campaign; passing the Message ID to the form (if it is known) will enable the reporting module to show detailed information.	4567890	No
ri	Record ID	Every record loaded into the system is given a Record ID to uniquely identify it; this ID is stored separately from the client-defined Unique Identifiers.	345678	No
	Data Properties	Each property for a recipient (i.e. First Name, Last Name, etc.) can be submitted as parameters, using the following rules: Single-value fields like First Name, Last Name, etc., follow the format of “s_<database field name>” Multi-value fields like check boxes for preferences follow the format of “m_<database field name>”	s_name_first=John s_name_last=Smith m_pref=Blue m_pref=Red m_pref=Green	No
	Unique Identifiers	Depending on the client configuration, the Unique Identifier field(s) must be submitted as part of the parameters to the Form so that the Form module can correctly identify if it's an existing record, or if a new record must be created. Note: Optionally, you can use the Soft Match feature if the Unique Identifier is not part of the request message.	s_account_number=95750243 s_email=john.smith@company.com	Yes