Subscriber Service Specification

Overview

The Subscriber Service Specification will send subscriber data to Aimbase and add subscribers to lists.

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  
}