How does moving a subscriber with the API affect custom fields?

AWeber’s API can help you automate many tasks, including moving subscribers between lists. Moving subscribers is generally pretty straightforward, but if you’re also using custom fields to track data for segmentation purposes you should be aware of how your API moves can affect that data.

Let’s start with an example. Say I have two lists in my account, List A and List B. On each list I want to track my subscribers’ phone number, favorite pizza topping, and favorite color. However the order in which I set up the custom fields is different for each list. A diagram of this situation might look like this:

There are a few outcomes to API moves with custom fields, and we’ll go over each case in turn.

Automatic Mapping When Custom Fields Match

If your list looks like our example list and the field names exactly match (case insensitively) except for the order, we will automatically map the fields. A diagram of the outcome would look like this:

So our example subscriber would have the phone number from the source list placed into the the phone number field on the destination list. We only do this automatically if all the fields have exactly the same name, and there are no extra fields on either list.

No Mapping of Custom Fields

This is the default case when you make an API move request and your custom field names do not line up exactly. This could happen if you have an additional field on your source or destination list. An example of an API move request with no enforcement of custom field mapping might look like this if you were using Python 3.6 and requests_oauthlib:

from requests_oauthlib import OAuth1Session

aweber = OAuth1Session(client_key, 
                       client_secret, 
                       resource_owner_key, 
                       resource_owner_secret)

data = {'ws.op': 'move',
        'list_link': 'https://api.aweber.com/1.0/accounts/{account_id}/lists/{list_id}'}

url = 'https://api.aweber.com/1.0/accounts/{account_id}/lists/{list_id}/subscribers/{subscriber_id}'
response = aweber.post(url, json=data)

print('Response code:', response.status_code)

In AWeber the order in which you define the fields matters. Let’s take the same example from earlier but we'll add a field called "Fax Number" to List B. In this case without custom field mapping, the API will move the fields over with the subscriber based on position. Whatever was in the first field will go to the first field on the new list, and so on. A diagram of what happens would look like this:

Notice how for our example API move where the fields don’t match exactly the subscriber on List A would have their phone number placed into the favorite color field on List B after they are moved. That could be a problem if we were trying to segment based on favorite color!

The benefit to using the move without mapping the fields is if you don’t have exactly the same number of fields on each list we’ll allow the move to happen anyway. So if you had an extra field on List A called “Fax Number” and we couldn’t find it on List B the subscriber could be moved anyway.

Enforcing Custom Field Mapping

If you would like the API to move your subscriber while maintaining your custom field data you can specify an extra parameter with your move request. Simply add “enforce_custom_field_mapping” to your request body with a value of “true” and the API will attempt to map your fields. A request with this parameter might look like this:

from requests_oauthlib import OAuth1Session

aweber = OAuth1Session(client_key, 
                       client_secret, 
                       resource_owner_key, 
                       resource_owner_secret)

data = {'ws.op': 'move',
        'list_link': 'https://api.aweber.com/1.0/accounts/{account_id}/lists/{list_id}', 
        'enforce_custom_field_mapping': 'true'}

url = 'https://api.aweber.com/1.0/accounts/{account_id}/lists/{list_id}/subscribers/{subscriber_id}'
response = aweber.post(url, json=data)

print('Response code:', response.status_code)

The API will match case sensitively first, then case insensitively. If all the source fields are present in the destination list, we’ll map the fields and allow the move to happen. If a field on the source list does not exist in the destination list the move will fail. A diagram for our example case would look like this:

This way, you can make sure all your data stays intact while managing your lists. As previously mentioned, the move will fail if all the fields are not present. So if List B had a field called “phone” but not “phone number” the move would fail. In addition if list A had the “Fax Number” field and it wasn’t present on List B the move would also fail.

With the AWeber API you are in control of your data. With the flexibility to map your custom fields or to ignore mappings you can build tools that fit your workflow and keep your business running smoothly. Have questions about a use case not covered in this article, or want to talk about how to use the API or custom fields to automate your email marketing? Send us an email at api@aweber.com and we’d be happy to help!