Overview 

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

Related APIs: 

• To filter, sort and retrieve registration records use the Registration Search API. 

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. 

2. Each registration is validated against the Registration XSD. 

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

4. 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 

Dealer Data Schema 

Customer Data Schema

Product Data Schema 

Custom Data Schema 

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>Registration</RegistrationTypeCode> 
        <RegistrationSourceCode>WebService</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" : "Registration", 
        "RegistrationSourceCode" : "WebService", 
        "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" : [] 
}