Follow

Conventions

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]

Data Fields

The Data argument requires additional fields to identify individual subscribers or email recipients.  For example, with a Subscribe command, the data argument represents a Subscriber to import and subscribe to a list.  Each data argument requires fields to identify a subscriber, such as email and first. 

The Subscriber Data fields include:

  • email
  • address_1
  • state
  • phone
  • first
  • address_2
  • zip
  • fax
  • last
  • city
  • country
  • company

Four additional Subscriber 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 subscriber will receive, you can set the format_number in the Data fields instead of as an argument. 

1  = plain text (DEFAULT)
2  = HTML
99 = Multi-part MIME

format_text

To specify the format of the email messages your subscriber will receive, you can set the format_text in the Data fields instead of as an argument. 

plain = plain text (DEFAULT)
HTML = HTML
mime = Multi-part MIME
multi = Multi-part MIME

customer_key

Subscriber's unique identification string.  Only available on some systems.  This field is required when enabled in the account 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.

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:

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:

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 subscriber 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:

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

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  

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk