Subscriber Service API

Overview

Use the Subscriber Service API to create a subscriber record in Aimbase and add to a list to send nurture or email campaigns.

Related APIs:

To retrieve subscriber status and optin information use the Subscriber Optin API.

Possible Response Codes

201 (Created). This response indicates that the subscriber was successfully created within Aimbase.
400 (Bad Request). Along with the 400 response, the body of the response will contain an error message describing why the request was a bad request.
- For subscriber type code {0} a value is required in the OptInListIds property. This response indicates that the particular subscriber code being passed requires an OptInListids.
- A value provided in the OptInListIds property was not valid. This response indicates that the OptInListIds is not located in Aimbase.
500 (Internal Server Error). An unknown error occurred during the import.

Authentication

The Subscriber Service requires authentication. The HTTP POST will require a valid Authenticate message header with an API token. See the Aimbase Authentication Web Service Specification for more details on how to retrieve a valid API token.

Authenticate message header example:

Authenticate: Avala-Api {username}:{token}

Post Information

HTTP Endpoint

https://{baseurl}/Marketing/api/subscriber?manufacturer={manufacturercode}

Subscriber Data Schema

Field Name	Required	Format	Description
Email	X	Max Length: 256
SubscriberTypeCode	X	Max Length: 50	Alphanumeric values that identify the type of subscriber
CountryCode	X	Max Length: 2
IsCommunicationOptIn	X	Boolean	A flag for identifying if the subscriber is opted in for future communications.
IsCommunicationOptInIpAddress		Max Length: 20	The IP Address of the subscriber when it was submitted. This field is required if IsCommunicationOptIn is true.
IsCommunicationOptInDate		yyyy-MM-dd	The date the subscriber opted in for communications. This field is required if IsCommunicationOptIn is true.
IsCommunicationOptInSource		Max Length: 50	The source of the subscriber that was opted in for communications. This field is required if  IsCommunicationOptIn is true.
ListCodes		Max Length: 100	A comma delimited list of Email List Codes that the subscriber should be added to. This will be done in addition to any other lists that the subscriber would ordinarily be assigned to due to the SubscriberTypeCode.
Brand		Max Length: 48	The brand for the subscriber, should come in as Brand Code from Aimbase.
Customs		Collection/Array of CustomData data schema.	Additional data arguments that can be configured for custom dealer properties and submitting in name/value pairs. If the values match anything in the CustomData Field Mapping table, it needs to match the FieldNames exactly.
LangCode		Max Length: 2	A language code will be flagged as invalid if no survey is set up for the given language code. Acceptable language codes: “DC”, “EN”, “FR”, “GR”, “IT”, “JP”, “PO”, “RK”, “SP”, “SW”. If not provided we default to EN.

CustomData Data Schema

Field Name	Required	Format	Description
FieldName	X	Max Length: 50, must match the values from CustomData Field Name Values if they correspond and would be included in campaign sends	The field name of the custom field.
FieldValue	X	Max Length: 2048	The field value of the custom field.

CustomData Field Name Values

Field Name	Format
FirstName	Max Length: 2048
LastName	Max Length: 2048
Address1	Max Length: 2048
Address2	Max Length: 2048
City	Max Length: 2048
State	Max Length: 2048
PostalCode	Max Length: 2048
County	Max Length: 2048
DealerName	Max Length: 2048
DealerNumber	Max Length: 2048
DealerAddress1	Max Length: 2048
DealerAddress2	Max Length: 2048
DealerCity	Max Length: 2048
DealerState	Max Length: 2048
DealerPostalCode	Max Length: 2048
DealerCounty	Max Length: 2048
DealerCountryCode	Max Length: 2048
ProductCode	Max Length: 2048
ProductName	Max Length: 2048
ProductModelYear	Max Length: 2048
ProductTypeName	Max Length: 2048
BrandName	Max Length: 2048
ManufacturerName	Max Length: 2048

NOTE: Anything not on this table can still be used, using whatever naming convention you would like. If these fields are not going to be used for campaign sends, they do not need to match the table.

XML Post Example

POST: https://{baseurl}/Marketing/api/subscriber?manufacturer={manufacturercode} 
Host: {baseurl} 
Authenticate: Avala-Api {username}:{token} 
Content-Type: application/xml
 
<Subscriber xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Email>subscriber@rollick.io</Email>
    <SubscriberTypeCode>Sub</SubscriberTypeCode>
    <CountryCode>US</CountryCode>
    <IsCommunicationOptIn>true</IsCommunicationOptIn>
    <IsCommunicationOptInIpAddress>197.1.1.111</IsCommunicationOptInIpAddress>
    <IsCommunicationOptInDate>2015-04-22T08:38:54.5525933-05:00</IsCommunicationOptInDate> 
    <IsCommunicationOptInSource>Website</IsCommunicationOptInSource>
    <ListCodes>List1,List2</ListCodes> 
    <Brand>XY</Brand> 
    <Customs> 
        <Custom> 
            <FieldName>Activities</FieldName> 
            <FieldValue>Boating</FieldValue> 
        </Custom> 
        <Custom> 
            <FieldName>Gender</FieldName> 
            <FieldValue>Male</FieldValue> 
        </Custom> 
    </Customs> 
    <LangCode>EN</LangCode> 
</Subscriber>

XML Response Example

<Subscriber xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Status>Success</Status> 
    <StatusMessage>Subscriber successfully updated.</StatusMessage> 
</Subscriber>

JSON Post Example

POST: https://{baseurl}/Marketing/api/subscriber?manufacturer={manufacturercode} 
Host: {baseurl} 
Authenticate: Avala-Api {username}:{token} 
Content-Type: application/json
 
{ 
 
    "Email": "subscriber@rollick.io", 
    "SubscriberTypeCode": "Sub", 
    "CountryCode": "US", 
    "IsCommunicationOptIn": true, 
    "IsCommunicationOptInIpAddress": "197.1.1.111", 
    "IsCommunicationOptInDate": "2015-04-22T08:38:54.5525933-05:00", 
    "IsCommunicationOptInSource": "Website", 
    "ListCodes": "List1, List2" 
    "Brand": "XY", 
    "Customs" : [ 
    { 
    "FieldName" : "Name1", 
    "FieldValue" : "Value1" 
    }, 
    { 
    "FieldName" : "Name2", 
    "FieldValue" : "Value2" 
    } 
  ] 
}

JSON Response Example

 {  
   "Status": "Success",  
   "StatusMessage": "Subscriber successfully updated.",  
   "TopLevelError": null,  
   "Messages": null  
}

Rollick Knowledge