Lead Search API

 

Overview 

Use the Lead Search API to filter, sort and retrieve leads across Aimbase. For example, use the endpoint to search for leads for a specific dealer and order by date. 

To search and update a lead, use the Lead Odata endpoint.

Possible response codes are: 

  • 200 (OK). The request was successful and the results will return.
  • 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. 
  • 500 (Internal Server Error). An unknown error occurred. 

The Lead 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. 

Authenticate message header example: 

Authenticate: Avala-Api {username}:{token} 

 

The HTTP endpoints that will accept the POST data are:  

https://{baseurl}/Marketing/API/LeadSearch  

 

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

 

Lead Search Data Schema 

Field Name  Required  Format  Description 
PageNumber    Number  The page number to return in the search results. Default: 1 
PageSize    Number  The size of the page to return in the search results. Min: 1, Max: 1000, Default: 20 
OrderBy      The string value of the field to order the results by. Valid values are: Id, LeadDate, CreateDate. Default: Id 
IsOrderByDescending    Boolean  A true/false value that indicates whether the OrderBy value should be ordered by ascending or descending.  Default: false 
ManufacturerCode     Max Length: 6  Filter the possible results by a specific manufacturer.  
ProductCode    Max Length: 50  Filter the possible results by a specific product’s code. 
ProductModelYear    Number  Filter the possible results by a specific product’s model year. 
BrandCode    Max Length: 50  Filter the possible results by a specific Brand’s code. 
DealerNumber    Max Length: 20  Filter the possible results by a specific dealer’s number. 
DealerLocation    Max Length: 10  Filter the possible results by a specific dealer’s location. 
LeadSourceCode    Max Length:20  Filter the possible results by a specific lead source’s code. 
LeadTypeCode    Max Length: 20  Filter the possible results by a specific lead type code. 
LeadCategoryCode    Max Length: 20  Filter the possible results by a specific lead category’s code. 
LeadCampaignCode    Max Length: 20  Filter the possible results by a specific lead campaign code. 
EventName    Max Length: 20  Filter the possible results by a specific event. 
BeginLeadDate    YYYY-MM-DD  Filter the possible results so that the lead must have a lead date after the given BeginLeadDate. 
EndLeadDate    YYYY-MM-DD  Filter the possible results so that the lead must have a lead date before the given EndLeadDate 
BeginCreateDate    YYYY-MM-DD  Filter the possible results so that the lead must have a create date after the given BeginCreateDate 
EndCreateDate    YYYY-MM-DD  Filter the possible results so that the lead must have a create date before the given EndCreateDate 
FirstName    Max Length: 50  Filter the possible results by a specific first name. 
LastName    Max Length: 50  Filter the possible results by a specific last name. 
Email    Max Length: 80  Filter the possible results by a specific email address. 

 

Sample POST (XML) 

<LeadSearchRequest>
    <PageSize>1</PageSize>
    <BeginLeadDate>2020-08-01</BeginLeadDate> 
    <EndLeadDate>2020-08-08</EndLeadDate>
    <OrderBy>LeadDate</OrderBy>
    <IsOrderByDescending>true</IsOrderByDescending>
    <LeadSourceCode>Organic</LeadSourceCode>
</LeadSearchRequest>

 

Sample POST (JSON) 

{ 
    "PageSize":"1",
    "BeginLeadDate": "2020-08-01", 
    "EndLeadDate": "2020-08-08",
    "OrderBy":"LeadDate",
    "IsOrderByDescending": true,
    "LeadSourceCode": "Organic" 
}

 

Sample Success XML Response 

<LeadSearchResponseModel 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Total>8</Total>
  <PageSize>1</PageSize>
  <PageNumber>1</PageNumber>
  <Leads>
    <LeadModel>
      <Id>77142</Id>
      <Uid>8628a80f-03d9-4aad-97e9-f2d1fcd231bf</Uid>
      <LeadDate>2020-08-07T12:26:37.81</LeadDate>
      <ManufacturerCode>MFG Code</ManufacturerCode>
      <ManufacturerName>Manufacturer Name</ManufacturerName>
      <LeadSourceCode>Organic</LeadSourceCode>
      <LeadTypeCode>Build Your Own</LeadTypeCode>
      <LeadCategoryCode>manufacturer.com</LeadCategoryCode>
      <EventName />
      <DealerNumber>1234</DealerNumber>
      <DealerName>Dealer A</DealerName>
      <DealerContact>Jim A</DealerContact>
      <DealerEmail>jima@dealera.com</DealerEmail>
      <DealerAddress1>123 Dealer Street</DealerAddress1>
      <DealerAddress2 />
      <DealerCity>Fenton</DealerCity>
      <DealerState>MO</DealerState>
      <DealerPostalCode>12345</DealerPostalCode>
      <DealerCountryCode>US</DealerCountryCode>
      <DealerPhone>111-111-1111</DealerPhone>
      <DealerFax />
      <ProductCode>Product1</ProductCode>
      <ProductModelYear>2020</ProductModelYear>
      <ProductModelName>Product 1</ProductModelName>
      <ProductBrandCode>BrandCode</ProductBrandCode>
      <ProductCategory>Product Category</ProductCategory>
      <ProspectUid>06578e05-7a00-44ab-9f47-07edbda772db</ProspectUid>
      <ProspectAggregationId>211284</ProspectAggregationId>
      <ProspectFirstName>John</ProspectFirstName>
      <ProspectLastName>Doe</ProspectLastName>
      <ProspectAddress1>145 Test St.</ProspectAddress1>
      <ProspectCity>fenton</ProspectCity>
      <ProspectState>MO</ProspectState>
      <ProspectPostalCode>63026</ProspectPostalCode>
      <ProspectCountryCode>US</ProspectCountryCode>
      <ProspectHomePhone>123-123-1234</ProspectHomePhone>
      <ProspectEmail>johndoe@gmail.com</ProspectEmail>
      <ProspectEmailRefused>false</ProspectEmailRefused>
      <CreateDate>2020-08-07T12:27:24.767</CreateDate>
      <Customs>
        <Custom>
          <FieldName>Comment</FieldName>
        </Custom>
        <Custom>
          <FieldName>Content</FieldName>
        </Custom>
        <Custom>
          <FieldName>CurrentlyOwn</FieldName>
        </Custom>
        <Custom>
          <FieldName>DownloadLink</FieldName>
        </Custom>
        <Custom>
          <FieldName>EngineColor</FieldName>
        </Custom>
        <Custom>
          <FieldName>InterestedIn</FieldName>
        </Custom>
        <Custom>
          <FieldName>PlanningToPurchase</FieldName>
        </Custom>
        <Custom>
          <FieldName>PurchaseTimeframe</FieldName>
          <FieldValue>3 to 6 months</FieldValue>
        </Custom>
        <Custom>
          <FieldName>TourDate</FieldName>
        </Custom>
        <Custom>
          <FieldName>TourTime</FieldName>
        </Custom>
      </Customs>
    </LeadModel>
  </Leads>
</LeadSearchResponseModel>

 

Sample Success JSON Response 

{
  "Leads": [
    {
      "Id": 77142,
      "Uid": "8628a80f-03d9-4aad-97e9-f2d1fcd231bf",
      "LeadDate": "2020-08-07T12:26:37.81",
      "ManufacturerCode": "MFGCode",
      "ManufacturerName": "Manufacturer Name",
      "LeadSourceCode": "Organic",
      "LeadTypeCode": "Build Your Own",
      "LeadCategoryCode": "manufacturer.com",
      "LeadCampaignCode": null,
      "EventName": "",
      "DealerNumber": "1234",
      "DealerLocation": null,
      "DealerName": "Dealer A",
      "DealerContact": "Jim A",
      "DealerEmail": "jima@dealera.com",
      "DealerAddress1": "123 Dealer Street",
      "DealerAddress2": null,
      "DealerCity": "Fenton",
      "DealerState": "MO",
      "DealerPostalCode": "12312",
      "DealerCountryCode": "US",
      "DealerPhone": "111-111-1111",
      "DealerFax": "",
      "DealerTollFree": null,
      "ProductCode": "Product1",
      "ProductModelYear": "2020",
      "ProductModelName": "Product 1",
      "ProductPlantCode": null,
      "ProductBrandCode": "BrandCode",
      "ProductCategory": "Product Category",
      "ProductSegment": null,
      "ProspectUid": "06578e05-7a00-44ab-9f47-07edbda772db",
      "ProspectAggregationId": 211284,
      "ProspectFirstName": "John",
      "ProspectLastName": "Doe",
      "ProspectTitle": null,
      "ProspectAddress1": "145 Test St.",
      "ProspectAddress2": null,
      "ProspectCity": "Fenton",
      "ProspectState": "MO",
      "ProspectPostalCode": "63026",
      "ProspectCountryCode": "US",
      "ProspectCompanyName": null,
      "ProspectCompanyTitle": null,
      "ProspectHomePhone": "123-123-1234",
      "ProspectMobilePhone": null,
      "ProspectWorkPhone": null,
      "ProspectFax": null,
      "ProspectEmail": "johndoe@gmail.com",
      "ProspectLanguageCode": null,
      "ProspectEmailRefused": false,
      "CreateDate": "2020-08-07T12:27:24.767",
      "Customs": [
        {
          "FieldName": "Comment",
          "FieldValue": null
        },
        {
          "FieldName": "Content",
          "FieldValue": null
        },
        {
          "FieldName": "CurrentlyOwn",
          "FieldValue": null
        },
        {
          "FieldName": "DownloadLink",
          "FieldValue": null
        },
        {
          "FieldName": "EngineColor",
          "FieldValue": null
        },
        {
          "FieldName": "InterestedIn",
          "FieldValue": null
        },
        {
          "FieldName": "PlanningToPurchase",
          "FieldValue": null
        },
        {
          "FieldName": "PurchaseTimeframe",
          "FieldValue": "3 to 6 months"
        },
        {
          "FieldName": "TourDate",
          "FieldValue": null
        },
        {
          "FieldName": "TourTime",
          "FieldValue": null
        }
      ]
    }
  ],
  "Total": 8,
  "PageSize": 1,
  "PageNumber": 1
}