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": {}
  }
}

Rollick Knowledge