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 |
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: 50 | 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 }