This topic describes URL structures and parameters used in the HTTP integration API for Episerver Campaign.
A URL for an HTTP API request has the following structure (example):
The components of the URL have the following meaning:
The root address of the HTTP-API for Episerver Campaign; called via an SSL connection:
Without SSL encryption, the root address starts with:
The service selector sets the service to be used. Currently, the form service (form) or mail service (mail) is available.
The authorization code. The operation is performed only if the authorization code is correct:
The operation selector defines the operation to be performed:
Parameters needed for the operation. See Parameters.
Almost any operation requires several parameters. Parameters that control an operation are prefixed with a bm (for example, "bmRecipientIdemail@example.com").
Note: The HTTP API expects case sensitive parameters. Make sure that you use the parameters in the correct upper and lower case. (For example: bmRecipientId instead of bmrecipientid.)
The following system parameters are accepted for each operation:
|If a URL is passed using this parameter, the result (success message) is forwarded to this URL after the operation is successfully performed. The GET parameter, bmResult, is appended to this URL. This parameter contains the success message, such as ok or ok:update.
Note: The bmSuccessUrl parameter takes priority over the bmUrl.
If a URL is passed using this parameter, the result (error message) is forwarded to this URL after the operation fails. The GET parameter bmResult is appended to this URL. This parameter contains the error message, such as duplicate or blacklisted.
Note: The bmFailureUrl parameter takes priority over the bmUrl.
If a URL is passed using this parameter, the result is forwarded to this URL after performing the operation (whether successful or failed). The GET parameter bmResult is appended to this URL. This parameter contains the notification message, such as ok or duplicate.
Note: This parameter can be replaced by bmSuccessUrl or bmFailureUrl to handle success and failure messages separately. bmSuccessUrl and bmFailureUrl take priority over bmUrl if used in the same operation.
This parameter defines the character set for the transmitted data. By default, it is set to iso-8859-1. If the characters are erroneous, try to set the value to utf-8. The encoding is particularly important if arrays of data are transmitted, for example when using the subscribe and updatefields operations.
To receive detailed success and failure messages, set the value of this parameter to true (for example, instead of ok, the message ok: removed is returned). By default, this parameter is set to false.
Note: Additional system parameters are described in the respective operation.
Data parameters designate a field of the same name in the recipient list, e.g., firstname=John (the parameter firstname contains the value John). If the field does not exist, the parameter is ignored. Otherwise, what happens to the value of this parameter depends on the particular operation. Typically, the content of the field in the database is overwritten with the given value.
Data parameters can:
The desired operation is added to the parameter using square brackets ().
Note: Make sure to transmit only URL-encoded data parameters.
The following symbols are used for URL encoding:
You can find the correct spelling of a recipient list's fields in the recipient list details. To do this, perform these steps:
The Show recipient list details window opens. Check the spelling of the recipient list fields.
Note: In an HTTP API request, you can use the display name as well as the internal name of a recipient list field.
The following formatting rules apply:
|int/long||Decimal notation without additional symbols.||10000 or 5|
|float/double||Decimal notation separated by a period (.).||12345.67|
|date/datetime||The following date formats are supported:
||2001-08-21T18:52:05+02:00 (+02:00 means CEST)|
Usually, operations return a value that contains a success or error message, such as OK: 32 or duplicate. You can use these return values to display a respective message in your form.
Many operations also support forwarding. After an operation is performed, the user is forwarded to a URL. The return message is added to that URL as an additional parameter (bmResult). For detailed information, see the operation description.
Note: If you use the parameter bmVerbose=true, a detailed message is returned (e.g., OK: already_unsubscribed).
Last updated: Apr 25, 2018