Add or update one or more subscribers to a preexisting mailing list. Set subscriber details email address, confirmation status and optional custom fields. You can specify whether to add that subscriber to autoresponders, whether they will receive HTML or text-based mailings, or if they should be tagged. 

User can also use this call to create a journey via the "send_newsletter" parameter.


Note: The functionality provided by this API call can also be achieved using the AddSubscribersToList call if user sets the "update_if_exits" element to `true`. 


Note:  This API call can also be found under the requesttype of "Lists".


JSON Request Example:    

{
  "username": "DRBrel2",
  "usertoken": "25cdc94232a34e752e150ca278e980d0416a390f",
  "requesttype": "Subscribers",
  "requestmethod": "AddOrUpdateSubscribers",
  "details": {
    "list": "{*list_id*}", /* required */
    "tag": ["{*tag_id or tag_name*}", "{*tag_id or tag_name*}"],
    "format": "{*email_format*}",
    "confirmed": "{*confirmed_boolean*}",
    "timezone": "{*timezone*}",
    "add_to_autoresponders": "{*add_to_autoresponders_boolean*}",
    "send_confirmation": "{*send_confirmation_boolean*}",
    "send_newsletter": "{*newsletter_id or newsletter_name*}",
    "contact": [
      { /* required: at least one */
        "email": "{*email_address*}", /* required */
        "mobilephone": "{*mobile_phone*}",
        "tag": ["{*tag_id or tag_name*}", "{*tag_id or tag_name*}"],
        "format": "{*email_format*}",
        "ipaddress": "{*ip_address*}",
        "confirmed": "{*confirmed_boolean*}",
        "timezone": "{*timezone*}",
        "add_to_autoresponders": "{*add_to_autoresponders_boolean*}",
        "send_confirmation": "{*send_confirmation_boolean*}",
        "send_newsletter": "{*newsletter_id or newsletter_name*}",
        "customfield": [
          {
            "fieldid": "{*custom_field_id*}",
            "value": "{*custom_field_value*}"
          },
          {
            "fieldid": "{*custom_field_id*}",
            "value": "{*custom_field_value*}"
          }
        ]
      },
      {
        "email": "{*email_address*}", /* required */
        "mobilephone": "{*mobile_phone*}",
        "tag": ["{*tag_id or tag_name*}", "{*tag_id or tag_name*}"],
        "format": "{*email_format*}",
        "ipaddress": "{*ip_address*}",
        "confirmed": "{*confirmed_boolean*}",
        "timezone": "{*timezone*}",
        "add_to_autoresponders": "{*add_to_autoresponders_boolean*}",
        "send_confirmation": "{*send_confirmation_boolean*}",
        "send_newsletter": "{*newsletter_id or newsletter_name*}",
        "customfield": [
          {
            "fieldid": "{*custom_field_id*}",
            "value": "{*custom_field_value*}"
          },
          {
            "fieldid": "{*custom_field_id*}",
            "value": "{*custom_field_value*}"
          }
        ]
      }
    ],
    "return_data": "{*return_data_boolean*}",
    "include_membership": "{*include_membership_boolean*}"
  }
}
Null

 "json_request" element


Field NameDescription
usernameUsername used to login to Pinpointe
usertokenUnique token assigned to Pinpointe account
requesttypeSubscribers
requestmethodAddOrUpdateSubscribers


Please note: ALL OPTIONAL elements that are not used should be deleted from submitted call. For example, if no IP address will be supplied as part of the call, "ipaddress": "{*ip_address*}", should be deleted. 


"details" element 

Note: this section is to apply element values globally to all contacts for the API call. Corresponding element values entered as part of a contact-specific entry as described below will override these global values.  


Field NameDescription
list
(Required globally or per contact)
Add all contacts to this global database mailing list with this ID number who do NOT have a contact-specific list-ID assign to them. See "list" description below under "contacts" section. 
tag
(optional global tag assignment)
Use one or more elements to assign global tag_id(s) to all subscribers who do NOT have a contact-specific tag_id assigned to them. Values can be the tag's numeric ID or the tag name. See "tag" description below under "contacts" section. 
format
(optional)		Use html to send user HTML emails or text for plain-text. html is the default.
confirmed
(optional)		Use true, 1 or yes to mark user as confirmed or false, 0 or no for unconfirmed. true is default
timezone
(optional)		Will accept US / Canadian time zones as local-specified (e.g. America/Los_Angeles) OR any of the US or Canadian short codes: EST, EDT, CST, CDT, MST, MDT, PST, PDT, etc. OR an offset from GMT/UTC. 
add_to_autoresponders
(optional)		Globally adds all contacts to autoresponders, if they exist using true, 1 or yes.   If you do not wish to add contacts to autoresponders, enter a value of false, 0 or no. false is default. Individual contacts may also be added to autoresponders.  See "add_to_autoresponders" description below under "contacts" section. 
send_confirmation
(optional)		Use true, 1 or yes to send contact(s) a confirmation email or false, 0 or no to not do so. false is default.
send_newsletter
(optional)		newsletter_id or newsletter_name to be sent. 
NOTE: Including this parameter will create a journey.


"details"

"contact" element


Field NameDescription
email
(required)		email address of contact to be added
mobilephone
(optional)		Mobile phone number of contact. Required for SMS messaging through Pinpointe.
tag
(optional)
Use one or more elements to assign tag_id(s) to this specific contact. Values can be the tag's numeric ID or the tag name. NOTE: contact-specific tag_ids or tag_names will take precedence over the global tag_id or tag_name specified under the global "details" section noted above.  
format
(optional)		Use html to send user HTML emails or text for plain-text. html is the default.
ipaddress
(optional)		Can add optional IP address.
confirmed
(optional)		Use true, 1 or yes to mark user as confirmed or false, 0 or no for unconfirmed. true is default
timezone
(optional)
Will accept US / Canadian time zones as local-specified (e.g. America/Los_Angeles) OR any of the US or Canadian short codes: EST, EDT, CST, CDT, MST, MDT, PST, PDT, etc. OR an offset from GMT/UTC. 
add_to_autoresponders
(optional)		Adds this specific contact to autoresponders, if they exist using true, 1 or yes   If you do not wish to add contact to autoresponders, enter a value of false, 0 or no. false is default. NOTE: This contact-specific value will take precedence over the global value if set above. 
send_confirmation
(optional)
Use true, 1 or yes to send contact(s) a confirmation email or false, 0 or no to not do so. false is default.
send_newsletter
(optional)
newsletter_id or newsletter_name to be sent. 
NOTE: Including this parameter will create a journey.


"customfield" OPTIONAL

"fieldid", "value" elements - add values for a subscriber's custom fields. Use one "fieldid" and "value" pair per custom field.

NOTE: you may insert multiple "customfield" elements to add/update multiple custom fields. 


Field NameDescription
fieldidID of custom field to be added.  
valueValue of this custom field

Please note: If no custom field data is to be sent, please delete the "customfield" tags and all inner tags to avoid a submission error. 


"return_data" and "include_membership" elements


return_data
Setting this element's value to true, 1 or yes results in the API call returning an expanded body of subscriber data required by some applications.
include_membership
PieSync requirement: Setting this element's value to true, 1 or yes results in the API call adding a list of all tags that a subscriber is in as part of the returned information for that subscriber.


Successful Response:


"response" element


Field NameDescription
statusWill return SUCCESS if contact(s) was / were successfully added


"Response" => "data" element


add_countNumber of contacts added to database by this call
update_countNumber of contacts updated in database by this call
journey_idJourney ID of created journey IF send_newsletter parameter included
subscribersID of subscribers enrolled in journey IF send_newsletter parameter included 
added Number of contacts added to journey IF send_newsletter parameter included 


Unsuccessful Response:


"response> element


Field NameDescription
statusWill return FAILED if unsuccessful
errormessageText explaining why request failed