Lead OData API

Overview

Use the Lead OData to retrieve and update lead information. This API supports multiple filter and expand options, allowing you to get a list of leads and all the information surrounding them. It will allow you to make an update to a lead, as well. 

If you are looking to POST or create a lead, you should visit the Lead API documentation

This is an OData endpoint and it will support the OData query language. More information about this can be found at odata.org

Possible Response Codes

  • 200 (OK). This request was successful and information will be returned.
  • 204 (No Content). The patch was successful. 
  • 400 (Bad Request). The request is invalid.
  • 401 (Unauthorized). The token is missing, invalid, or expired.
  • 404 (Not Found). The lead was not able to be found.
  • 500 (Internal Server Error). The request was malformed, the lead given in the request did not exist, or some other unspecified error occurred when attempting to retrieve lead information.

Authentication

The Lead OData API requires authentication. The GET and PATCH request will require a valid Authenticate message header with an API token. See the Aimbase Authentication API for more information on how to authenticate your request. 

Authenticate message header example:

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

Query Information

This OData API allows GET and PATCH. 

Endpoint for GET

GET https://{baseurl}/odata/V2/Leads

Endpoint for PATCH

PATCH https://{baseurl}/odata/V2/Leads

Lead OData Data Schema 

The information below will be returned in a GET. It can also be updated via a PATCH.

Name

Editable

Values

Description

Id
Integer The Aimbase ID of the lead.
ExternalId
String (50) An external system ID that can be passed in with the lead or updated later.
LeadUid
UID The lead's unique identifier.
ProspectId
Integer The prospect's Aimbase identifier.
DealerId
Integer The dealer's Aimbase identifier.
ProductId
Integer The product's Aimbase identifier.
LeadDate X YYYY-MM-dd ±hh:mm The date the lead was entered.
ViewedDate
YYYY-MM-dd ±hh:mm The date the lead was viewed by the assigned contact. 
Event X String (50) The event on the lead.  
Score
Integer The score on the lead
CreateDate
YYYY-MM-dd ±hh:mm The creation date of the lead
UpdateDate
YYYY-MM-dd ±hh:mm The latest update date of the lead
CreateAccountId
Integer The id of the account that created the lead
UpdateAccountId
Integer The id of the account that last updated the lead
SentDate
YYYY-MM-dd ±hh:mm The date the lead was sent to the contact
Medium X String (200) The medium on the lead
ScoreText
String (30) The computed text of the score on the lead
ProspectInterestId
Integer The id of the prospect interest
IsActive
Boolean If the lead is in an active state or not.
StagingLeadId
Integer The staging lead ID of the lead
DealerDistance
Integer Distance of the lead from the assigned dealer
DealerDistanceMiles
Integer Distance in miles of the lead from the assigned dealer
IsQualified
Boolean If the lead is qualified or not
FollowUpStatusCode X String The follow up status code of the lead.
PurchaseStatusCode X String The purchase status code of the lead.
LeadTypeCode X String The lead type code for the lead
LeadCategoryCode X String The lead category code for the lead
LeadSourceCode X String The lead source code for the lead
LeadCampaignCode X String The lead campaign code for the lead
LeadStatusCode X String The lead status code for the lead. Default is Pending. 
ConditionCode X String The condition of the product New (N), Used (U) or Showroom (S). 
Customs X Customs Custom fields defined in Aimbase are listed as "FieldName" : "FieldValue" under the customs object. 
Metadata X Metadata If any metadata appears on the lead, it will be listed as "FieldName":"FieldValue" under the metadata object. 

Expand Options 

The prospect information is not included by default, but you can expand the lead object to get prospect information on the lead as well. When you expand, you will get additional fields related to the prospect that the lead belongs to. This includes first and last name, email, and more.  

Prospect Fields on Expand

Field Name 

Editable

Format 

Description 

Id 


 

The prospect record’s identifier. 

ExternalId 


 

The prospect record’s external identifier for external systems (if available). 

ProspectUid 


UID 

The prospect record’s UID. 

ProspectAggregationId
  The prospect record's aggregation identifier.

CompanyId 


 

The prospect’s company ID if applicable. 

LastName 

X

 

The prospect’s last name. 

FirstName 

X

 

The prospect’s first name. 

Title 

X

 

The prospect’s title or salutation. 

Address1 

X

 

The prospect’s mailing address line 1. 

Address2 

X

 

The prospect’s mailing address line 2. 

City 

X

 

The prospect’s mailing address city. 

State 

X

 

The prospect’s mailing address state. 

PostalCode 

X

 

The prospect’s mailing address postal code. 

ZIP4 

X

 

The prospect’s mailing address +4 zipcode numbers. 

CompanyName 

X

 

The name of the company the prospect works for. 

CompanyTitle 

X

 

The prospect’s job title at their company. 

County 

X

 

The prospect’s mailing address county. 

Country 

X

 

The prospect’s mailing address country name. 

HomePhone 

X

 

The home phone number of the prospect. 

WorkPhone 

X

 

The work phone number of the prospect. 

Fax 

X

 

The fax number of the prospect. 

Email 

X

 

The email address of the prospect. 

PhoneRefused 

X

 

The prospect’s phone refused value. 

TextRefused 

X

 

The prospect’s text refused value. 

MailRefused 

X

 

The prospect’s mail refused value. 

FIPSCode 

X

 

The FIPS code of the prospect’s mailing address county. 

CensusCode 

X

 

The prospect’s census code value. 

CassCertified 

X

 

The prospect’s cass certified value. 

CountryCode 

X

 

The prospect’s mailing address country code (ISO 3166-1 alpha-2) 

MobilePhone 

X

 

The mobile phone number of the prospect. 

AddrStatus 

X

 

The prospect’s address status value. 

AddrError 

X

 

The prospect’s address error description value. 

LangCode 

X

 

The prospect’s language code (ISO 639-1) 

CassOverride 

X

 

The prospect’s cass override value. 

IsActive 


Boolean 

Indicates if the prospect record is active or inactive. 

IsInvalidEmail 


Boolean 

Indicates if the prospect’s email address is an incorrectly formatted email address. 

IsAddressCleaned 


Boolean 

Indicates if the prospect’s mailing address has been cleaned by an address standardizing service. 

EmailRefused 

X

Boolean 

Indicates if the prospect has refused emails. 

Score 


Number 

The prospect’s score value. 

ScoreText 


 

The prospect’s score text value. If the prospect’s score is greater than 100, it will be displayed as “100+” 

LegacyCustomerId 


Number 

The prospect’s legacy customer ID value. 

OriginProspectType 


 

The original prospect type that was set on the prospect record when it was created. 

CurrentProspectType 

X

 

The most up to date prospect type for the prospect. 

CompetitiveBrand 

X

 

The prospect’s competitive brand value. 

Latitude 

X

 

The latitude value of the prospect’s postal code. 

Longitude 

X

 

The longitude value of the prospect’s postal code. 

IsNurtured 

X

Boolean 

Indicates if the prospect should receive nurture emails. 

CreateDate 


 

The time the prospect was created. 

UpdateDate 


 

The time the prospect was last updated. 

Customs 


Collection of Custom Data 

The custom data associated with the Prospect. 

Sample Queries

Get All Leads - Default Page Size 1,000

GET http://{baseurl}/odata/V2/Leads

Get a Lead and Expand Prospect

GET https://{baseurl}/odata/V2/Leads(114)?$expand=Prospect

Patch a Lead

PATCH https://{baseurl}.aimbase.com/odata/V2/Leads(114)
Content-Type: application/json
Authenticate: Avala-Api {username}:{token}


{
    "Medium": "Medium"
}

Example Response (expanded by Prospect)

{
  "@odata.context": "https://{baseurl}/odata/V2/$metadata#Leads/$entity",
  "Id": 114,
  "ExternalId": "1481995",
  "LeadUid": "cc16dda6-8c50-483b-a928-cc506817cc33",
  "ProspectId": 74712,
  "DealerId": 1565,
  "ProductId": 6064,
  "LeadDate": "2016-08-29T15:31:01-05:00",
  "ViewedDate": null,
  "Event": null,
  "Score": 0,
  "CreateDate": "2016-11-22T00:14:41.47-06:00",
  "UpdateDate": null,
  "CreateAccountId": 0,
  "UpdateAccountId": null,
  "SentDate": "2016-08-29T15:32:04.997-05:00",
  "Medium": null,
  "ScoreText": "0",
  "ProspectInterestId": 1,
  "IsActive": true,
  "StagingLeadId": null,
  "DealerDistance": null,
  "DealerDistanceMiles": null,
  "IsQualified": true,
  "FollowUpStatusCode": "Contacted",
  "PurchaseStatusCode": "Unknown",
  "LeadTypeCode": "LeadType",
  "LeadCategoryCode": "LeadCategory",
  "LeadSourceCode": "Website",
  "LeadCampaignCode": null,
  "LeadStatusCode": "Pending",
  "Customs": {
    "BuyTimeFrame": null,
    "Comment": null,
  },
  "Metadata": {},
  "Prospect": {
    "Id": 74712,
    "ExternalId": null,
    "ProspectUid": "b118e079-22ab-493f-8237-83f3e397d1b2",
    "ProspectAggregationId": 85651,
    "CompanyId": null,
    "LastName": "Jane",
    "FirstName": "Doe",
    "Title": null,
    "Address1": "",
    "Address2": "",
    "City": "",
    "State": "CA",
    "PostalCode": "93023     ",
    "ZIP4": null,
    "CompanyName": null,
    "CompanyTitle": null,
    "County": null,
    "Country": "United States",
    "HomePhone": "111-222-3300",
    "WorkPhone": "",
    "Fax": null,
    "Email": "jane.doe@rollick.io",
    "PhoneRefused": false,
    "TextRefused": false,
    "MailRefused": false,
    "FIPSCode": null,
    "CensusCode": null,
    "CassCertified": null,
    "CountryCode": "US",
    "MobilePhone": "",
    "AddrStatus": null,
    "AddrError": null,
    "LangCode": null,
    "CassOverride": null,
    "IsActive": true,
    "IsInvalidEmail": false,
    "IsAddressCleaned": false,
    "EmailRefused": false,
    "Score": 0,
    "ScoreText": "0",
    "LegacyCustomerId": 2885537,
    "OriginProspectType": "Website",
    "CurrentProspectType": "Website",
    "CompetitiveBrand": "",
    "Latitude": 34.448123,
    "Longitude": -119.252560,
    "IsNurtured": true,
    "HomePhoneNumeric": "8054523040",
    "WorkPhoneNumeric": "",
    "MobilePhoneNumeric": "",
    "CreateDate": "2016-11-22T00:14:23.327-06:00",
    "UpdateDate": null,
    "CreateAccountId": 0,
    "UpdateAccountId": null,
    "Customs": {}
  }
}