API Release Notes | December 2013

The December 2013 API update is planned for Friday, December 6, 2013. Please read through these API release notes to get the skinny on what’s in it.

New Features

OAuth 2.0 Migration Endpoints

We’re releasing two brand new endpoints for you to use in migrating your existing users from either OAuth 1.0a or Basic authentication to OAuth 2.0. We really want our developers to start moving their apps to using our OAuth 2.0 authentication flows. OAuth 2.0 is simpler to use than OAuth 1.0a, is more secure, and provides specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. OAuth 2.0 authentication is required to use our v2 APIs.

We’ve included recommended workflows you should follow for each migration type in the API Docs – see Basic to OAuth 2.0  and OAuth 1.0a to OAuth 2.0 for the details

EventSpot Promocode endpoints

In October we introduced the EventSpot collection of event management endpoints as a Beta release. Nowr we’re adding two new endpoints to manage promotional codes (promocodes) that are applied to event fees:

  • Promocode Collection
    uri – https://api.constantcontact.com/v2/eventspot/events/{event_id}/promocodes
    GET all promocodes associated with an event, or create (POST) a new promocode.
  • Individual Promocodes
    uri -https://api.constantcontact.com/v2/eventspot/events/{eventId}/promocodes/{promocodeId}
    Get, update (PUT), and DELETE specific promocodes for an event.

Email Campaign preview endpoint

Use this endpoint to retrieve a preview of an email campaign. The preview shows both the HTML and text versions of the email campaign. See the API documentation for detailed information.
uri – https://api.constantcontact.com/v2/emailmarketing/campaigns/{campaignid}/preview

Enhancements

“state” property added to Contact endpoints

The state field accepts any state or province name. However, if a valid 2 letter US state or Canadian province is entered in the state_code field, the system resolves the code to a state or province and overwrites any name manually entered in this (state) field.
uri – https://api.constantcontact.com/v2/contacts

Email content validation

Leon and Kenny changed the way the API validates email campaign content so that it is consistent with the product GUI. We anticipate that this change will eliminate a multitude of erroneous “json.invalid.value.no_script_tags” error messages developers have seen related to email campaign content.

“label” property added to custom_field for Contact endpoints

The label property was added to the custom_fields array; for accounts using the new contacts management system, this read-only field displays the custom_field name entered using the product GUI. For accounts using the legacy contact management system, the value is displayed only if it matches the CustomFieldnn (n=1-15) format.

MyLibrary files pagination upped to 1000 records

The limit parameter maximum value for a GET call to the MyLibrary file collection endpoint has been upped to 1000.

Date-time string parser enhanced

Hardik and Rohan have changed the date time string parser/validator the API uses. The date-time parser is much less restrictive, and can parse all but a very few date, time, or date-time strings. The API continues to return standard ISO-8601 dates in GMT time zone – YYYY-MM-DDTHH:MM:SS.sssZ. Here are some examples showing previously invalid input and how it is now parsed by the API:

2014      >> 2014-01-11T00:00:00.000Z
2014-01-11   >> 2014-01-11T00:00:00.000Z
2013-10-23T15:16:02.254Z   >> 2013-10-23T15:16:02.254Z
1999-W50    >> 1999-12-13T00:00:00.000Z
T15:16:02.254    >> 1970-01-01T15:16:02.254Z
1997-07-16T19:20:30.4+01:00 >> 1997-07-16T18:20:30.400Z

Unsupport date-time formats:

  • YYYYMMDD – 19991101
  • YYYYMM – 199901
  • YYYYWww – 1999W50
  • HH:MM:SS.sss – 15:16:02.254
  • THHMMSS.sss – T151602.254
  • YYYYWwwD – 2014W361
  • YYYYDDD – 2014136

Check out the documentation for all the details.

Bugs Fixed

WSPI-4518 – Leon fixed the bug that caused the next_link in the return of GET calls to MyLibrary trash folder, folder, and file collection endpoints to be the same URL in each page of a multi-page return.

WSPI-4130 – Corrected an issue that was causing failures for a GET https://api.constantcontact.com/v2/contacts?status=REMOVED for accounts using the new contact management system.

WSPI-4714 – I corrected the JSON request example in the Add & Update Contacts – Bulk Activities API documentation.  Special thanks to TimB6901 for finding the error, and ScottS980 for providing the corrected example in our Developer Forum.

WSPI-4713 – A bug that caused the API to send an error on email campaigns with a state or country name in the footer without a 2-letter state or country code is now fixed. The API accepts campaigns created in the product GUI without a state or country 2-letter abbreviation.

Known Bugs

WSPI-4758 – There is a bug in the Add Contacts Bulk Activities API in processing CustomField values that contain a comma.  Thanks to SamV5 for identifying this bug in our Developer Forum.

uri: https://api.constantcontact.com/v2/activities/addcontacts
Behavior seen: For custom field values containing a comma, i.e.

“name”:“Custom Field 10”,
“value”: “Smith, John”,

The value after the comma (John) is be placed in Custom Field n+1 (11), all values for subsequent custom fields is bumped up to  Custom Field n+1, and any value in Custom Field 15 is lost.

Workaround: Wrap any custom field value containing a comma with escaped double quotes
“value”:”\”Smith,John\””,

Fix: We’re working on a fix that we expect to deploy on December 10, 2013.

WSPI-4732 – A duplicate contact is created when using the V1 Add Contacts Bulk API for accounts that use the new contact management system.  Thanks to askrenes for reporting this issue in the Developer Forum.

Behavior seen: When using the Add Contacts Bulk API, if the last field in the payload is an email address, duplicate checking is not performed on that email address. This applies to the V1 API, and to accounts using the new contact management system.

Workaround: Make sure that last field in payload is not an email address; if necessary, include a blank CustomField, or other “dummy” as the last entry in the import file.

WSPI-3888 – We are aware of a bug that causes calls to the Bulk Activity Remove Contacts endpoint to fail for accounts using the new contact management system.
uri – https://api.constantcontact.com/v2/activities/removefromlists
Thanks to devteamd for reporting this issue in the Developer Forum.

Leave a Comment