Overview 

The Dealer Contact Search API is used for searching contacts that are configured to receive notifications on behalf of a dealership.

Dealer contact search 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 

• 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 Search 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. 

Authentication

The Dealer Contact Search API 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://{baseaddress} /api/DealerContactSearch?manufacturer={manufacturerCode} 

Dealer Data Schema 

XML Example Post

<Dealers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Dealer> 
        <DealerNumber>1000</DealerNumber> 
    </Dealer> 
</Dealers> 

JSON Example Post

[
  { 
"DealerNumber" : "0", 
"DealerLocation" : null 
  }
]

Sample Success Response (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 retrieved</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 retrieved", 
"Messages" : [] 
} 
] 
}

Sample Failed Response (XML/JSON)

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

<?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 Contacts failed validation</StatusMessage> 
                <Messages> 
                    <Message> 
                        <Field>DealerNumber</Field> 
                        <Message>The DealerNumber field is required.</Message> 
                    </Message> 
                </Messages> 
                <Contacts /> 
            </Dealer> 
</Dealers> 

{ 
"TopLevelError" : null, 
"DealerContactResponseRecords" : [{ 
"DealerNumber" : null, 
"DealerLocation" : null, 
"Contacts" : [], 
"Id" : null, 
"Status" : "Failure", 
"StatusMessage" : "Dealer Contacts failed validation", 
"Messages" : [{ 
"Field" : "DealerNumber", 
"Message" : "The DealerNumber 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" : [] 
}