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
}