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. | |
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 }