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 when in this default 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 

Contact Data Schema 

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> 
                <Title>Manager</Title> 
                <PrimaryPhoneNumber>800-242-8877</PrimaryPhoneNumber> 
                <SecondaryPhoneNumber>314-290-8891</SecondaryPhoneNumber> 
                <Fax></Fax> 
                <IsActive>true</IsActive> 
                <CountryCode>US</CountryCode>
                <ContactTypeNames> 
                    <string>Lead Emails To</string> 
                    <string>Satisfaction Emails To</string> 
                </ContactTypeNames> 
            </Contact> 
        </DealerContacts> 
    </Dealer> 
</Dealers>

APPENDIX B – Sample POST (JSON) 

[{ 
        "DealerNumber" : "1000", 
        "DealerContacts" : [{ 
                "FirstName" : "John", 
                "LastName" : "Doe", 
                "Email" : "jdoe@email.com", 
                "Title" : "Manager",
                "PrimaryPhoneNumber" : "800-242-8877",
                "SecondaryPhoneNumber" : "314-290-8891",
                "Fax" : null,
                "IsActive" : true, 
                "CountryCode" : "US",
                "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" : [] 
}