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
}