The HTTP API interface allows you to send commands to a web based servlet via POST or GET. All HTTP API commands are handled through api_web. The fully qualified URL is:
http://[siteurl]/bin/api_web
where 'siteurl' is the URL you use to access the API for your system. If you are on the Professional Edition SaaS, the URL would be:
http://api.whatcounts.net/bin/api_web
You can submit data to the servlet via POST or GET. Testing with a browser is performed through GET. To handle any significant amount of data, you must run the command through POST. If you test through your browser, you will likely reach a limit of 1,000 characters, a limitation of GET. POST has no predefined limit.
The HTTP API takes several arguments, three of which are always required. Please note the case of each argument in documentation, as the api is case sensitive.
| Name | Description | Argument |
| Command | The command tells the API what task to perform. | cmd=[command] c=[command] |
| Realm | Authentication is based on realm and password. The realm name is determined when your account is created, and can be seen in the Welcome message you receive with your platform login credentials. The realm must be defined first. | realm= [realm_name] r=[realm_name] |
| Password | The password, also known as an authentication code, must be defined after the realm. | pwd=[password] p=[password] password=[password] |
| API Client* |
Client authentication provides another level of user access and security. This is optional instead of using the Default API Client. API Client is available to better manage clients' access and usage of APIs. Each realm has a default API Client which requires only the Realm and Password above. When using one of the four possible API Clients, the API Client Name and Client Authentication must also be included in the header. To define an API Client, login to the platform and then go to CUSTOMER CENTER > API MANAGEMENT > SETUP API. You must generate the Authorization Code, then generate the API Password If using an API client, define it after the password. **Added in v15.02** |
api_client=[client_name] |
| API Client Authorization | Changing the API Client Authorization code invalidates any files using the old code. If the authorization code already exists and you regenerate it, make sure to notify everyone using the API Client in any of the APIs. This is required when using any API Client other than Default. | client_auth=[client_auth] |
Data Fields
The Data argument requires additional fields to identify individual contacts or email recipients. For example, with a Subscribe command, the data argument represents a Contact to import and subscribe to a list. Each data argument requires fields to identify a contact, such as email and first. All date fields require a 2 digit month, 2 digit date, and four digit year, such as 03/27/2019, 2019-03-27.
The Contact Data fields include:
|
|
|
|
|
|
|
|
|
|
|
|
|
Four additional Contact Data fields are used for special values:
|
duplicate |
To force duplicates, a unique first name must be identified, and the duplicate field must be set to 1. |
|
format_number |
To specify the format of the email messages your contact will receive, you can set the format_number in the Data fields instead of as an argument. 1 = plain text (DEFAULT) |
|
format_text |
To specify the format of the email messages your contact will receive, you can set the format_text in the Data fields instead of as an argument. plain = plain text (DEFAULT) |
|
customer_key |
Contact's unique identification string. Only available on some systems. This field is required when enabled in the realm settings. |
Custom Fields
Custom fields can be specified by appending the string “custom_” to the field name. For example, if your realm has a custom field named “age”, specify it as a data field using “custom_age”. If you are attempting to import custom data and the data remains blank in the database, check that the custom field has been properly identified in the data file preceded by “custom_”.
Please note that custom fields are case sensitive and long names or names with spaces are prone to error. All date fields require a 2 digit month, 2 digit date, and four digit year, such as 03/27/2019, 2019-03-27.
Separators and Delimiters
Commands that require a list of data use a separator between the data definition and the data values, as well as a delimiter between each data value. The default separator and delimiter are acceptable for most use cases, especially when the data values have been enclosed in double quotes, however there are instances where one or both of the characters occur in a data value, and therefore must be redefined.
For example, the following subscribe command uses the default separator (^) and delimiter (,) with no issues:
/bin/api_web?c=sub&r=myrealm&p=mypass&list_id=5&data=email,first,last,custom_special^jane@domain.com,Jane,Doe,special+text
However, the following subscribe command uses the default separator (^) and delimiter (,) and the data values also contain the same characters:
/bin/api_web?c=sub&r=myrealm&p=mypass&list_id=5&data=email,first,last,custom_special^jane@domain.com,Jane,Doe,special^text1,special^text2
In the second example, the custom_special field contains both a caret and a comma. The caret causes the parser to think there is another row of contact data to import. If there were no caret, the comma would cause the parser to think that an extra Data Field was required. The two solutions for this issue are either double-quoting the data values and/or custom defining the separator and delimiter in the command. For example:
/bin/api_web?c=sub&r=myrealm&p=mypass&list_id=5&data=email,first,last,custom_special^"jane@domain.com","Jane","Doe","special^text1,special^text2"
OR
/bin/api_web?c=sub&r=myrealm&p=mypass&list_id=5&separator=~&delimiter=|&data=email,first,last,custom_special^jane@domain.com|Jane|Doe|special^text1,special^text2
You may find that in most cases you will not need to define either separator or delimiter, and in some instances you may need only one or the other.
Avoid using the following characters, as they are already in use in the commands:
|
Character |
HEX |
|
|
space |
|
%20 |
|
ampersand |
& |
%26 |
|
plus |
+ |
%2B |
|
comma |
, |
%2C |
|
forward slash |
/ |
%2F |
|
quote |
' |
%27 |
|
double quote |
" |
%22 |
|
caret |
^ |
%5E |
|
question |
? |
%3F |
|
underscore |
_ |
%5F |
|
equals |
= |
%3D |
|
percent |
% |
%25 |
Suggested substitutions include:
|
Character |
HEX |
|
|
line feed |
|
%0A |
|
carriage return |
|
%0D |
|
tilde |
~ |
%7E |
|
pipe |
| |
%7C |
Return Values
Most commands return SUCCESS and descriptive information if the operation is successful or FAILURE and a reason if the operation fails. The default output for other results is a single, wrapped line of text separated by spaces. You can specify the format you would like output and include column headers, or labels, for CSV results.
To change the returned format, use one of the following arguments in your command:
|
Argument |
Description |
|
&csv=1 |
Return quoted, comma separated values (CSV) output. |
|
&output_format=csv |
Return quoted, comma separated values (CSV) output. |
|
&output_format=csv_pipe
|
Return quoted CSV output, but separate fields using the pipe (|) character. |
|
&output_format=csv_tab |
Return quoted CSV output, but separate fields using the tab (\t) character. |
|
&output_format=xml |
Return XML output. |
|
&headers=1 |
Include headers for the CSV output. |
Special Characters
Since the HTTP API commands can be used through a browser, you may need to replace some special characters with URL friendly versions. For example, use of the carrot (^) character to represent a new line. In addition, you can use the return (\r) and newline (\n) variations to represent line breaks.
When sending data that contains a space character through a browser, be sure to use the plus (+) character or URL Encoded space (%20) to replace the space.
Other characters you may find you need to replace include the following:
|
Character |
HEX |
|
|
space |
|
%20 |
|
ampersand |
& |
%26 |
|
plus |
+ |
%2B |
|
comma |
, |
%2C |
|
period |
. |
%2E |
|
forward slash |
/ |
%2F |
|
colon |
: |
%3A |
|
semi-colon |
; |
%3B |
|
less than |
< |
%3C |
|
greater than |
> |
%3E |
|
question |
? |
%3F |
As an exception, the double quote character (") must be escaped using the backslash (\). For instance, the text:
This sentence contains "quoted" text
Would be escaped as:
"This sentence contains \"quoted\" text"
Where each double quote is preceded by a backslash, and the entire data string is enclosed in quotation marks. If you do not quote the entire string, the command may fail. The escaped quotes will be ignored and the string may be improperly stored as:
This sentence contains \quoted" text