Basic Usage and Terminology

Authentication

We authenticate over HTTPS with Basic Forms Authentication. Depending on your tools this will have different implementations but in .Net you're going to do something like this.

Dim h As New System.Net.WebClient
h.Credentials = New System.Net.NetworkCredential("USERNAME", "PASSWORD")

Authorization

We secure access to dealership information by attaching PartnerHub Accounts to certain Dealerships. Each dealership is associated with a specific Serial Number that you can use to Query and Update and across all our Services you'll see reference to the dealership SerialNumber. An Account is related to a number of Serial Numbers and if you try to access a Serial Number you don't have access to you'll get an ugly error.

<ContactGet xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/PBS.PartnerHub.ServiceModel">
  <ContactCode>String</ContactCode>
  <ContactId>00000000-0000-0000-0000-000000000000</ContactId>
  <EmailAddress>String</EmailAddress>
  <LastName>String</LastName>
  <ModifiedSince>0001-01-01T00:00:00</ModifiedSince>
  <PhoneNumber>String</PhoneNumber>
  <SerialNumber>String</SerialNumber>
</ContactGet>

Request/Response

Every Action you can perform has a response type of ActionResponse. This makes it really easy to understand what Actions are related to what Responses. For example the ContactGet action has a ContactGetResponse. The XML representation looks like this...

<ContactGet xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/PBS.PartnerHub.ServiceModel">
  <ContactCode>String</ContactCode>
  <ContactId>00000000-0000-0000-0000-000000000000</ContactId>
  <EmailAddress>String</EmailAddress>
  <LastName>String</LastName>
  <ModifiedSince>0001-01-01T00:00:00</ModifiedSince>
  <PhoneNumber>String</PhoneNumber>
  <SerialNumber>String</SerialNumber>
</ContactGet>

<ContactGetResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/PBS.PartnerHub.ServiceModel">
  <Contacts>
    <Contact>
      <Address>String</Address>
      <ApartmentNumber>String</ApartmentNumber>
      <BirthDate>0001-01-01T00:00:00</BirthDate>
      <BusinessPhone>String</BusinessPhone>
      <CellPhone>String</CellPhone>
      <City>String</City>
      <Code>String</Code>
      <ContactName>String</ContactName>
      <County>String</County>
      <EmailAddress>String</EmailAddress>
      <FaxNumber>String</FaxNumber>
      <FirstName>String</FirstName>
      <HomePhone>String</HomePhone>
      <Id>00000000-0000-0000-0000-000000000000</Id>
      <IsBusiness>false</IsBusiness>
      <IsInactive>false</IsInactive>
      <LastName>String</LastName>
      <LastUpdate>0001-01-01T00:00:00</LastUpdate>
      <MiddleName>String</MiddleName>
      <Notes>String</Notes>
      <Salutation>String</Salutation>
      <SerialNumber>String</SerialNumber>
      <State>String</State>
      <ZipCode>String</ZipCode>
    </Contact>
  </Contacts>
</ContactGetResponse>

There is one exception to this. Certain Actions have no specific response other than to say whether or not processing was completed. For these Actions we will generate a generic Confirmation response which basically provides a WasSuccessful property and a generic Message placeholder. Generally you'll see these types of responses whenever you ask to update data.

<ContactChange xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/PBS.PartnerHub.ServiceModel">
  <ContactInfo>
    <Address>String</Address>
    <ApartmentNumber>String</ApartmentNumber>
    <BirthDate>0001-01-01T00:00:00</BirthDate>
    <BusinessPhone>String</BusinessPhone>
    <CellPhone>String</CellPhone>
    <City>String</City>
    <Code>String</Code>
    <ContactName>String</ContactName>
    <County>String</County>
    <EmailAddress>String</EmailAddress>
    <FaxNumber>String</FaxNumber>
    <FirstName>String</FirstName>
    <HomePhone>String</HomePhone>
    <Id>00000000-0000-0000-0000-000000000000</Id>
    <IsBusiness>false</IsBusiness>
    <IsInactive>false</IsInactive>
    <LastName>String</LastName>
    <LastUpdate>0001-01-01T00:00:00</LastUpdate>
    <MiddleName>String</MiddleName>
    <Notes>String</Notes>
    <Salutation>String</Salutation>
    <SerialNumber>String</SerialNumber>
    <State>String</State>
    <ZipCode>String</ZipCode>
  </ContactInfo>
</ContactChange>

<Confirmation xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/PBS.PartnerHub.ServiceModel">
  <Message>String</Message>
  <WasSuccessful>false</WasSuccessful>
</Confirmation>

Verbs

The basic Verbs that we support are designed around Querying and Updating information. All our Query actions are named Get and all our Update verbs are named Change. When you get into the Meta page you're going to see some reference to a verb named Save - ignore these. They're an internal action that allow us to feed information in and out of the Partner Hub.

<ContactGet xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/PBS.PartnerHub.ServiceModel">
  <ContactCode>String</ContactCode>
  <ContactId>00000000-0000-0000-0000-000000000000</ContactId>
  <EmailAddress>String</EmailAddress>
  <LastName>String</LastName>
  <ModifiedSince>0001-01-01T00:00:00</ModifiedSince>
  <PhoneNumber>String</PhoneNumber>
  <SerialNumber>String</SerialNumber>
</ContactGet>

<ContactChange xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/PBS.PartnerHub.ServiceModel">
  <ContactInfo>
    <Address>String</Address>
    <ApartmentNumber>String</ApartmentNumber>
    <BirthDate>0001-01-01T00:00:00</BirthDate>
    <BusinessPhone>String</BusinessPhone>
    <CellPhone>String</CellPhone>
    <City>String</City>
    <Code>String</Code>
    <ContactName>String</ContactName>
    <County>String</County>
    <EmailAddress>String</EmailAddress>
    <FaxNumber>String</FaxNumber>
    <FirstName>String</FirstName>
    <HomePhone>String</HomePhone>
    <Id>00000000-0000-0000-0000-000000000000</Id>
    <IsBusiness>false</IsBusiness>
    <IsInactive>false</IsInactive>
    <LastName>String</LastName>
    <LastUpdate>0001-01-01T00:00:00</LastUpdate>
    <MiddleName>String</MiddleName>
    <Notes>String</Notes>
    <Salutation>String</Salutation>
    <SerialNumber>String</SerialNumber>
    <State>String</State>
    <ZipCode>String</ZipCode>
  </ContactInfo>
</ContactChange>