Aimbase Dealer Contact API

Overview 

This API is used for sending dealer contact data to Aimbase for existing dealers. To create a new dealer, see the Dealer Create/Update API.

Dealer contact 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”. 

 

Possible response codes are: 

  • 201 (Created). This response indicates that the dealer contact data was successfully parsed. The body of the response will contain the success or failure status for each dealer that was submitted in the request. NOTE: The response record details for each dealer will be returned in the order that they were submitted. 

  • 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 C for the structure of the error response. 

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

 

The Dealer Contact 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 HTTP endpoints that will accept the POST data are:  

  • https://{baseaddress} /api/DealerContact?manufacturer={manufacturerCode} 

Additionally, the url can contain an optional query string parameter: overrideContacts. The default behavior is overrideContacts=false and in this mode only contacts specified in the post data are modified. When overrideContacts=true is specified, for each dealer in the post data, all contacts in the system that are not in the post data are marked as inactive. 

 

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

 

Dealer Data Schema 

Field Name 

Required 

Format 

Description 

DealerNumber 

X 

Max Length: 20 

 

DealerLocation 

 

Max Length: 10 

 

DealerContacts 

 

 

A list of Contact data values.  

Contact Data Schema 

Field Name 

Required 

Format 

Description 

FirstName 

 

Max Length: 80 

 

LastName 

 

Max Length: 80 

 

Email 

X 

Max Length: 100 

 

IsActive 

X 

Boolean 

Inactive dealer contacts are not sent notifications. 

ContactTypeNames 

 

 

A list of contact type names that the contact should have. 

 

APPENDIX A – Sample POST (XML) 

<Dealers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Dealer> 
        <DealerNumber>1000</DealerNumber> 
        <DealerContacts> 
            <Contact> 
                <FirstName>John</FirstName> 
                <LastName>Doe</LastName> 
                <Email>jdoe@email.com</Email> 
                <IsActive>true</IsActive> 
                <ContactTypeNames> 
                    <string>Lead Emails To</string> 
                    <string>Satisfaction Emails To</string> 
                </ContactTypeNames> 
            </Contact> 
        </DealerContacts> 
    </Dealer> 
</Dealers>


APPENDIX B – Sample POST (JSON) 

[{ 
        "DealerNumber" : "1000", 
        "DealerLocation" : null, 
        "DealerContacts" : [{ 
                "FirstName" : "John", 
                "LastName" : "Doe", 
                "Email" : "jdoe@email.com", 
                "IsActive" : true, 
                "ContactTypeNames" : ["Lead Emails To", "Satisfaction Emails To"] 
            } 
        ] 
    } 
]


APPENDIX C – Sample Success Responses (XML/JSON) 

<Dealers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Dealer> 
        <Status>Success</Status> 
        <StatusMessage>Dealer's contacts successfully updated.</StatusMessage> 
        <Messages /> 
        <DealerNumber>1000</DealerNumber> 
        <Contacts> 
            <Contact> 
                <FirstName>John</FirstName> 
                <LastName>Doe</LastName> 
                <Email>jdoe@email.com</Email> 
                <IsActive>true</IsActive> 
                <ContactTypeNames> 
                    <string>Lead Emails To</string> 
                    <string>Satisfaction Emails To</string> 
                </ContactTypeNames> 
            </Contact> 
            <Contact> 
                <Email>testdealer@test.com</Email> 
                <IsActive>true</IsActive> 
                <ContactTypeNames> 
                    <string>Lead Emails CC</string> 
                    <string>Satisfaction Emails CC</string> 
                </ContactTypeNames> 
            </Contact> 
        </Contacts> 
    </Dealer> 
</Dealers> 
{ 
    "TopLevelError" : null, 
    "DealerContactResponseRecords" : [{ 
            "DealerNumber" : "1000", 
            "DealerLocation" : null, 
            "Contacts" : [{ 
                    "FirstName" : "John", 
                    "LastName" : "Doe", 
                    "Email" : "jdoe@email.com", 
                    "IsActive" : true, 
                    "ContactTypeNames" : ["Lead Emails To", "Satisfaction Emails To"] 
}, { 
                    "FirstName" : null, 
                    "LastName" : null, 
                    "Email" : "testdealer@test.com", 
                    "IsActive" : true, 
                    "ContactTypeNames" : ["Lead Emails CC", "Satisfaction Emails CC"] 
                } 
            ], 
            "Id" : null, 
            "Status" : "Success", 
            "StatusMessage" : "Dealer's contacts successfully updated.", 
            "Messages" : [] 
        } 
    ] 
}

 

APPENDIX D – Sample Failed Responses (XML/JSON) 

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

<?xml version="1.0"?> 
<Dealers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Dealer> 
        <Status>Failure</Status> 
        <StatusMessage>Dealer failed validation</StatusMessage> 
        <Messages> 
            <Message> 
                <Field>DealerContacts[0].Email</Field> 
                <Message>The Email field is required.</Message> 
            </Message> 
        </Messages> 
        <DealerNumber>1000</DealerNumber> 
        <Contacts /> 
    </Dealer> 
</Dealers> 
 
{ 
    "TopLevelError" : null, 
    "DealerContactResponseRecords" : [{ 
            "DealerNumber" : "1000", 
            "DealerLocation" : null, 
            "Contacts" : [], 
            "Id" : null, 
            "Status" : "Failure", 
            "StatusMessage" : "Dealer failed validation", 
            "Messages" : [{ 
                    "Field" : "DealerContacts[1].Email", 
                    "Message" : "The Email field is required." 
                } 
            ] 
        } 
    ] 
} 

 

The error responses below were generated by submitting a contact with data that could not be parsed into the correct format. 

<Dealers 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, 118).</Message> 
    </TopLevelError> 
</Dealers> 
 
{ 
    "TopLevelError" : { 
        "Message" : "Bad request: Unexpected end when deserializing array. Path '[0]', line 20, position 1., The Email field is required." 
    }, 
    "DealerContactResponseRecords" : [] 
}