Updating Tags for Contacts with API v3

[_Mystic_Chorale]

Hello:

I have a few questions concerning updating tags for contacts with version 3 of the API. Before I get to my question, some brief background:

I am in the process of updating our Constant Contact integration from version 2 to version 3 of the API. Without going into too much detail we are a choral group where people register to sing for a season (fall 2020 , winter 2020, spring 2020 etc). For each season we have been creating a separate email list in Constant Contact for the season. When people register for a season we use the API to add them to the mailing list for the season.

Recently we received an email notification from Constant Contact recommending that we use tags instead of creating a separate email list for each season. For example when someone registers for a season instead of creating a mailing list for the season the contact would be tagged with a tag for the season (for example fall-2020).

Checking the API documentation I did not see any documentation for tags. Should I be using the segments feature for this functionality? If so would the proper way to do this be to create the segment for the season in our Constant Contact account then use version 3 of the API to add or remove the contact as needed from the segment?

One last question concerning version 3 of the API. I am planning on using the endpoint which allows you to create or update a contact with the single method (https://v3.developer.constantcontact.com/api_guide/contacts_create_or_update.html). In reviewing the documentation I noticed that you are required to add the person to at least one list id. Do I need to create a list specifically for this? If I am using segments to tag contacts by season I don't really need to add them to a list. Is there a default list in our account I can use for this?

Hope all of the above makes sense! Please get back to me when you have a chance.

[Jimmy_D]

Hi @_Mystic_Chorale,

The tags option is not yet available in our v3 API. We did implement the segments option first and this would be a perfect way to use your contacts based on your description.

Concerning the endpoint you mentioned. That endpoint is more designed to replicate a sign-up form and that is why it is required to have a listID attached. You can still use that endpoint, but keep in mind that is not its designed use and there may be other issues such as accidentally resubscribing a contact; please read all of the documentation attached to that endpoint.

You can use our normal PUT to update a contact, or if you have multiple contacts you can use our BULK import method which is very similar to the endpoint you mentioned. https://v3.developer.constantcontact.com/api_guide/import_contacts.html

[_Mystic_Chorale]

Hi Jimmy:

Thank you for your detailed reply. I spent some more time reviewing the documentation and have a few more follow up questions. Please get back to me on these when you have a chance.

1. What attracted me to the endpoint I mentioned was that it allows you to either add the contact if it doesn't exist or update the contact if it does exist in a single call. From the documentation I read on the other end point for adding a contact it returns a 409 error if the contact exists, then you have to make a second call to update the contact.

The one potential conflict I thought of was related to the requirement that at least one list ID be specified. We could easily create a dummy list in our account to add contacts to. However if the contact is an existing contact can I specify to add them to this list without overriding any other lists the contact already belongs to? Hope that makes sense!

2. Is there any specific reason why we can't continue to create a new email list for each season and add/remove contacts from this list via the API as needed? I would still like to reserve this method as an option if my solution for using segments (see question 3 below) is not viable.

3. I reviewed the documentation concerning segments and outlined a potential solution for managing our season lists with this feature. I wanted to run this outline by you to make sure this would be a viable solution before attempting to implement it:

• Use the custom fields option within our Constant Contact account to create a custom field for contacts for active season. This active season custom field would have as the value the season the singer is registering for (Winter 2021 etc).
• When the singer registers use the API to update the contact setting the active season custom field to the season being registered for.
• In our Constant Contact account create a segment which would send emails to contacts with the active season value for the singers for a specific season. For example we could create a segment to send an email to everyone with the active season of Winter 2021.

Hope that makes sense! What I was confused about is whether segments can be created within the admin for our account. I would prefer to avoid trying to manage the segments themselves through the API, it would be easier if I can do something like what I outlined above where a custom field is used to identify singers by season.

Thanks again for your help!

-Robert

[David_B.]

Hello Robert,

1. That is correct. An alternative is to first do a GET to see if a contact exists and if it does, update that contact by modifying the data that is returned. If it does not exist, you can then POST to create a new individual contact.

2. The only real limitation you might run into is that your account can have a maximum of 1000 lists, and creating a new list each time can lead to a lot of unnecessary lists cluttering the Contacts page.

3. That's a good summary of how that feature can work and should suffice for your use case.

Please let us know if you have any other questions!

Regards,

David B.
Tier II API Support Engineer