Registration API

Overview 

Use the Registration API to create a new registration record in Aimbase. 

Related APIs: 


Registration data is submitted to our API via HTTP POST. The API will accept JSON or XML based on what content type is set in the Content-Type HTTP header. To submit JSON data set the Content-Type header to “application/json”, to submit XML set the Content-Type HTTP header to “application/xml”. 

The Registration API requires authentication so 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} 

The process flow of sending registration(s) to the system is as follows: 

  1. New registrations should be included in a request sent via an HTTP POST to the end point.  The request may contain one or more registrations. 

  1. Each registration is validated against the Registration XSD. 

  1. A response is generated containing a success or failure for each registration provided in the request. 

  1. Any registration successfully passing the first wave of validation checks will be assigned an Id that uniquely identifies the record in the staging process.  This Id will be included in the response. 

Possible response codes are: 

  • 201 (Created)This response indicates that the Registration data was successfully parsed. The body of the response will contain the success or failure status for each registration that was submitted in the request. 

  • 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. See Appendix D for the structure of an error response. 

  • 500 (Internal Server Error). An unknown error occurred during the import. 

 

The HTTP endpoint that will accept the POST data are:  

  • https://{baseaddress}/csi/api/registration?manufacturer={MFGcode} 

Note, {baseaddress} and {MFGcode} will be provided by Rollick.  

 

Below is the list of properties that are accepted in the POST body. 

 

Registration Data Schema 

Field Name 

Required 

Format 

Description 

IsActive 

 

Max Length: 1 

Bit value to determine if the registration is active or inactive. A Value of “1” indicates an active registration. A value of “0” indicates an inactive registration. No value provided will default to "1".  

Action 

 

Max Length: 1 

Pass the following values “A” for adding a record and “O” for updating a record. If blank it will default to adding a record.  

SrvyType 

 

Max Length: 1 

Survey Type. 

PurchaseDate 

X 

Max Length: 10 

YYYY-MM-DD 

Date of purchase 

DeliveryDate 

 

Max Length: 10 

YYYY-MM-DD 

Date of delivery 

SerialNumber 

X 

Max Length: 100 

Also referred to as HIN. This is a unique ID per survey.  

Dealer 


 

Node containing dealer specific information. 

Product 

X 

 

Node containing product specific information (name). 

Customer 

 

 

Node containing customer specific information. 

Price 

 

 

Price of the product being registered. 

PriceCurrency 

 

Max Length: 5 

Country currency for the registration price. 

SalesID 

 

Max Length: 200 

Sales identification number. 

StockNbr 

 

Max Length: 200 

Stock Number 

CompanyUid

 

Max Length: 200 

Company Uid

CompanyExternalId

 

Max Length: 20

Company External Id

ListCodes

 

Max Length: 

128

List codes

IsCommunicationOptIn 

 

Boolean 

Acceptable values are 'true' or 'false' 

CommunicationOptInIpAddress 

 

Max Length: 20 

The IP Address of the registration when it was submitted.  

CommunicationOptInDate 

 

yyyy-MM-dd 

The date the registration opted in for communications. 

CommunicationOptInSource 

 

Max Length: 50 

The source of the registration that was opted in for communications.  

RegistrationTypeCode 

 

Max Length: 20 

Record level registration type designation. 

RegistrationSourceCode 

 

Max Length: 20 

Record level registration source designation. 

SendSurvey 

 

 

Send survey override.  Acceptable values: "true" or "false"  

Customs 

 

 

A list of custom fields and their values. If the field name is defined as a custom field in the application, the value will be set for that field. If the field name is not defined as a custom field in the application, the field name and value will be added to the registration’s generic metadata values. 

Dealer Data Schema 

Field Name 

Required 

Format 

Description 

DealerNumber 

X 

Max Length: 20 

Manufacturer dealer number. Used to identify a dealer in the system. This value must not contain a hyphen.

DealerLocation 

 

Max Length: 10 

Manufacturer dealer location. Used to identify a dealer’s sub location in the system. 

DealerType 

X 

Max Length: 20 

Dealer type

Name 

X 

Max Length: 80 

Name of the dealer 

Contact 

 

Max Length: 50 

Primary dealer contact 

Email 

 

Max Length: 1000 

Email address of dealership. 

Address1 

 

Max Length: 256

 

Address2 

 

Max Length: 256 

 

City 

 

Max Length: 35 

 

State 

 

Max Length: 3 

 

PostalCode 

 

Max Length: 10 

 

CountryCode 

 

Max Length: 2 

 

Url 

 

Max Length: 80 

 

Phone 

 

Max Length: 20 

 

Fax 

 

Max Length: 20 

 

TollFree 

 

Max Length: 20 

 

District 

 

Max Length: 50 

 

Customs 

 

 

A list of custom fields and their values. If the field name is defined as a custom field in the application, the value will be set for that field. If the field name is not defined as a custom field in the application, the field name and value will be added to the dealer’s generic metadata values. 

Customer Data Schema

Field Name 

Required 

Format 

Description 

CustNumber 

X 

Max Length: 20 

Unique identifier or value used in the manufacturer system to identify the customer.

FirstName 

X 

Max Length: 50 

 

LastName 

X 

Max Length: 50 

 

Title 

 

Max Length: 50 

 

Address1 

X 

Max Length: 256 

 

Address2 

 

Max Length: 256 

 

City 

X 

Max Length: 35 

 

State 

 

Max Length: 3 

If and international country is passed State will "Not" be required. 

PostalCode 

 

Max Length: 10 

 

CompanyYN 

 

Max Length: 1 

“Y” or “N” value indicating if the customer is a company. Defaults to not a company if no value is given. 

CompanyName 

 

Max Length: 50 

 

CompanyTitle 

 

Max Length: 50 

 

County 

 

Max Length: 50 

 

CountryCode 

X 

Max Length: 2 

 

HomePhone 

 

Max Length: 20 

 

MobilePhone 

 

Max Length: 20 

 

WorkPhone 

 

Max Length: 20 

 

Fax 

 

Max Length: 20 

 

Email 

 

Max Length: 80 

 

LanguageCode 

X 

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”. Language codes are ISO 639-1.  

EmailRefused 

 

Max Length: 5 

Acceptable values are “True” or “False” 

ExternalId 

 

Max Length: 50 

External ID for the owner 

Product Data Schema 

Field Name 

Required 

Format 

Description 

Code 

X 

Max Length: 50 

 

ModelYear 

 

Max Length: 4 

 

ModelName 

 

Max Length: 80 

Human readable product name. If not supplied this field will be populated with the value of the Code field. 

PlantCode 

 

Max Length: 6 

 

Brand 

 

Max Length: 50 

Brand Code 

Category 

 

Max Length: 3 

 

Segment 

 

Max Length: 3 

 

EngineMake1 

 

Max Length: 50 

 

EngineModel1 

 

Max Length: 50 

 

EngineSerialNb1 

 

Max Length: 50 

 

EngineFuelSystem1 

 

Max Length: 50 

 

EngineMake2 

 

Max Length: 50 

 

EngineModel2 

 

Max Length: 50 

 

EngineSerialNb2 

 

Max Length: 50 

 

EngineFuelSystem2 

 

Max Length: 50 

 

Customs 

 

 

A list of custom fields and their values. If the field name is defined as a custom field in the application, the value will be set for that field. If the field name is not defined as a custom field in the application, the field name and value will be added to the product’s generic metadata values. 

Custom Data Schema 

Field Name 

Required 

Format 

Description 

FieldName 

X 

Max Length: 50 

The field name of the custom field. 

FieldValue 

X 

Max Length: 2048 

The field value of the custom field. 

 

APPENDIX A – Sample POST (XML) 

<Registrations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Registration> 
        <IsActive>false</IsActive> 
        <SrvyType>A</SrvyType> 
        <PurchaseDate>2014-07-06T17:32:00.0369673-05:00</PurchaseDate> 
        <SerialNumber>1111111</SerialNumber> 
        <Dealer> 
            <DealerLocation>1</DealerLocation> 
            <DealerNumber>12312</DealerNumber> 
            <Name>Test Dealer 1</Name> 
            <Contact>Test Contact 1</Contact> 
            <Email>test@testdealer1.com</Email> 
            <Address1>123 Main Street</Address1> 
            <Address2>A2</Address2> 
            <City>New York</City> 
            <State>NY</State> 
            <PostalCode>11111</PostalCode> 
            <CountryCode>US</CountryCode> 
            <Phone>13146209999</Phone> 
            <Fax>13146209998</Fax> 
            <TollFree>13146209997</TollFree> 
            <District>D1</District> 
            <Customs /> 
        </Dealer> 
        <Product> 
            <Code>TP1</Code> 
            <ModelYear>2014</ModelYear> 
            <ModelName>Test Product 1</ModelName> 
            <PlantCode>PC1</PlantCode> 
            <Brand>Brand1</Brand> 
            <Category>C1</Category> 
            <Segment>S1</Segment> 
        </Product> 
        <Customer> 
            <CustNumber>1231A</CustNumber> 
            <FirstName>John</FirstName> 
            <LastName>Doe</LastName> 
            <Title>Mr.</Title> 
            <Address1>123 Broadway Drive</Address1> 
            <Address2>Apt #2</Address2> 
            <City>Saint Louis</City> 
            <State>NO</State> 
            <PostalCode>63103</PostalCode> 
            <CompanyYN>N</CompanyYN> 
            <CompanyName>England</CompanyName> 
            <CompanyTitle>King</CompanyTitle> 
            <County>Saint Louis City</County> 
            <CountryCode>US</CountryCode> 
            <HomePhone>13146209999</HomePhone> 
            <MobilePhone>13146209998</MobilePhone> 
            <WorkPhone>13146209997</WorkPhone> 
            <Fax>13146209996</Fax> 
            <Email>jdoe@test.com</Email> 
            <LanguageCode>EN</LanguageCode> 
            <EmailRefused>0</EmailRefused> 
        </Customer> 
        <Price>234567</Price> 
        <PriceCurrency>USD</PriceCurrency> 
        <SalesID>1111A</SalesID> 
        <StockNbr>1111A</StockNbr> 
        <RegistrationTypeCode>RTC</RegistrationTypeCode> 
        <RegistrationSourceCode>RSC</RegistrationSourceCode> 
        <IsCommunicationOptIn>true</IsCommunicationOptIn> 
<CommunicationOptInIpAddress>99.999.99.999</CommunicationOptInIpAddress> 
<CommunicationOptInDate>2016-09-15T10:49:12.53</CommunicationOptInDate> 
<CommunicationOptInSource>Source</CommunicationOptInSource> 
<SendSurvey>true</SendSurvey> 
        <Customs> 
            <Custom> 
                <FieldName>Field1</FieldName> 
                <FieldValue>FieldValue1</FieldValue> 
            </Custom> 
            <Custom> 
                <FieldName>Field2</FieldName> 
                <FieldValue>FieldValue2</FieldValue> 
            </Custom> 
        </Customs> 
    </Registration> 
</Registrations>

APPENDIX B – Sample POST (JSON) 

[{ 
        "IsActive" : false, 
        "SrvyType" : "A", 
        "PurchaseDate" : "2014-07-06T17:34:13.1466117-05:00", 
        "SerialNumber" : "1111111", 
        "Dealer" : { 
            "DealerLocation" : "1", 
            "DealerNumber" : "12312", 
            "Name" : "Test Dealer 1", 
            "Contact" : "Test Contact 1", 
            "Email" : "test@testdealer1.com", 
            "Address1" : "123 Main Street", 
            "Address2" : "A2", 
            "City" : "New York", 
            "State" : "NY", 
            "PostalCode" : "11111", 
            "CountryCode" : "US", 
            "Phone" : "13146209999", 
            "Fax" : "13146209998", 
            "TollFree" : "13146209997", 
            "District" : "D1", 
            "Customs" : [] 
        }, 
        "Product" : { 
            "Code" : "TP1", 
            "ModelYear" : "2014", 
            "ModelName" : "Test Product 1", 
            "PlantCode" : "PC1", 
            "Brand" : "Brand1", 
            "Category" : "C1", 
            "Segment" : "S1", 
            "Customs" : null 
        }, 
        "Customer" : { 
            "CustNumber" : "1231A", 
            "FirstName" : "John", 
            "LastName" : "Doe", 
            "Title" : "Mr.", 
            "Address1" : "123 Broadway Drive", 
            "Address2" : "Apt #2", 
            "City" : "Saint Louis", 
            "State" : "NO", 
            "PostalCode" : "63103", 
            "CompanyYN" : "N", 
            "CompanyName" : "England", 
            "CompanyTitle" : "King", 
            "County" : "Saint Louis City", 
            "CountryCode" : "US", 
            "HomePhone" : "13146209999", 
            "MobilePhone" : "13146209998", 
            "WorkPhone" : "13146209997", 
            "Fax" : "13146209996", 
            "Email" : "jdoe@test.com", 
            "LanguageCode" : "EN", 
            "EmailRefused" : "0" 
        }, 
        "Price" : 234567.0, 
        "PriceCurrency" : "USD", 
        "SalesID" : "1111A", 
        "StockNbr" : "1111A", 
        "RegistrationTypeCode" : "RTC", 
        "RegistrationSourceCode" : "RSC", 
        "Customs" : [{ 
                "FieldName" : "Field1", 
                "FieldValue" : "FieldValue1" 
            }, { 
                "FieldName" : "Field2", 
                "FieldValue" : "FieldValue2" 
            } 
        ] 
    } 
] 

APPENDIX C – Sample Success Responses (XML/JSON) 

<Registrations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Registration> 
        <Id>0</Id> 
        <Status>Success</Status> 
        <StatusMessage>Registration successfully received</StatusMessage> 
        <Messages /> 
        <SerialNumber>1111111</SerialNumber> 
    </Registration> 
</Registrations> 
 
{ 
    "TopLevelError" : null, 
    "RegistrationResponseRecords" : [{ 
            "SerialNumber" : "1111111", 
            "Id" : "0", 
            "Status" : "Success", 
            "StatusMessage" : "Registration successfully received", 
            "Messages" : [] 
        } 
    ] 
}

APPENDIX D – Sample Failed Responses (XML/JSON)  

The error responses below were generated by submitting a Registration without the required field “LastName”. 

<Registrations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Registration> 
        <Status>Failure</Status> 
        <StatusMessage>Registration failed validation</StatusMessage> 
        <Messages> 
            <Message> 
                <Field>Customer.LastName</Field> 
                <Message>The LastName field is required.</Message> 
            </Message> 
        </Messages> 
        <SerialNumber>1111111</SerialNumber> 
    </Registration> 
</Registrations> 
 
{ 
        "TopLevelError" : null, 
        "RegistrationResponseRecords" : [{ 
                "SerialNumber" : "1111111", 
                "Id" : null, 
                "Status" : "Failure", 
                "StatusMessage" : "Registration failed validation", 
                "Messages" : [{ 
                    "Field" : "Customer.LastName", 
                    "Message" : "The LastName field is required." 
                } 
            ] 
        } 
    ] 
} 

 

The error responses below were generated by submitting a Registration that could not be parsed into the correct data schema. 

<Registrations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <TopLevelError> 
<Message>Bad request: There is an error in XML document (1, 130).</Message> 
    </TopLevelError> 
</Registrations> 
 
{ 
    "TopLevelError" : { 
        "Message" : "Bad request: Unexpected end when deserializing array. Path '[0]', line 75, position 1." 
    }, 
    "RegistrationResponseRecords" : [] 
}