Prospect OData API

Overview

The Prospect OData API provides a way to retrieve and update prospect information. It has multiple filter and expand options, allowing you to get a list of prospects and all the information surrounding them. It will allow you to make an update to a prospect as well. 

To update search for or update a lead, see our Lead OData API.

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 prospect was not able to be found.
  • 500 (Internal Server Error). The request was malformed, the prospect given in the request did not exist, or some other unspecified error occurred when attempting to retrieve lead information.

Authentication

The Prospect 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/Prospects

Endpoint for PATCH

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

Prospect OData Data Schema 

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

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. 

HomePhoneNumeric


Number

The numeric value of the home phone.

WorkPhoneNumeric


Number

The numeric value of the work phone.

MobilePhoneNumeric


Number

The numeric value of the mobile phone.

CreateDate 


 

The time the prospect was created. 

UpdateDate 


 

The time the prospect was last updated. 

CreateAccountId



The identifier of the account that created the prospect.

UpdateAccountId



The identifier of the account that last updated the prospect.

Customs 

X

Collection of Custom Data 

The custom data associated with the Prospect listed as "FieldName" : "FieldValue" under the customs object. 

Expand Options 

The lead information is not included by default, but you can expand the prospect object to get lead information. When you expand, you will get additional fields related to the lead. If the prospect has multiple leads, they are returned in a collection under the Leads object.

The Prospect OData API also allows expansion for Manufacturer information. This will help in the case of multiple manufacturers per install.

Lead Fields on Expand

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

Manufacturer Fields on Expand

Name

Editable

Values

Description

Id
Integer The Aimbase ID of the manufacturer
HierarchyId
Integer The ID of the hierarchy.
Code

String The code of the manufacturer that is defined in Aimbase.
Name

String The name of the manufacturer from Aimbase
Address1

String The address of the manufacturer.
Address2

String The address 2 of the manufacturer.
City

String The city of the manufacturer.
State

String The state of the manufacturer.
County

String The county of the manufacturer
Country

String The country of the manufacturer
DisplayOrder
Int Display order from Aimbase.
IsActive

Boolean If the manufacturer is active or not.
Latitude

Decimal Latitude calculated from address.
Longitude

Decimal Longitude calculated from address.
CreateDate

YYYY-MM-dd ±hh:mm
Create date of the manufacturer.
UpdateDate

YYYY-MM-dd ±hh:mm
Update of the manufacturer.
CreateAccountId

Int The account ID of who created the manufacturer.
UpdateAccountId

Int The account ID of the last update account for the manufacturer.
Email

String The email of the manufacturer
DomainId
Int The domain ID for the manufacturer

Sample Queries

Get First 10 Prospects

GET http://{baseurl}/odata/V2/Prospects?$top=10

Get a Prospect and Expand Leads

GET http://{baseurl}/odata/V2/Prospects(88048)?$expand=Leads

Patch Prospect's First Name

PATCH https://{baseurl}/odata/V2/Prospects(2)
Content-Type: application/json
Authenticate: Avala-Api {username}:{token}


{
  "FirstName": "Jane"
  "Customs": {
     "FieldName" : "FieldValue"
  }
}

Example Response (Expanded by Lead)

{
  "@odata.context": "https://{baseurl}/odata/V2/$metadata#Prospects/$entity",
  "Id": 88048,
  "ExternalId": null,
  "ProspectUid": "0ed74e8b-d33d-4ec1-a26f-7700c5ff4f37",
  "ProspectAggregationId": 87073,
  "CompanyId": null,
  "LastName": "Doe",
  "FirstName": "Jane",
  "Title": null,
  "Address1": "159 Jane Lane",
  "Address2": "",
  "City": "John",
  "State": "KY",
  "PostalCode": "40312     ",
  "ZIP4": null,
  "CompanyName": null,
  "CompanyTitle": null,
  "County": null,
  "Country": "United States",
  "HomePhone": "",
  "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": 2886959,
  "OriginProspectType": "Website",
  "CurrentProspectType": "Website",
  "CompetitiveBrand": "",
  "Latitude": 37.839660,
  "Longitude": -83.936520,
  "IsNurtured": true,
  "HomePhoneNumeric": "",
  "WorkPhoneNumeric": "",
  "MobilePhoneNumeric": "",
  "CreateDate": "2016-11-22T00:14:23.327-06:00",
  "UpdateDate": null,
  "CreateAccountId": 0,
  "UpdateAccountId": null,
  "Customs": {},
  "Leads": [
    {
      "Id": 1,
      "ExternalId": "1484059",
      "LeadUid": "d3323958-56cc-4c01-9bfe-da7eeb41e096",
      "ProspectId": 88048,
      "DealerId": 1669,
      "ProductId": 6256,
      "LeadDate": "2016-09-27T09:49:32-05:00",
      "ViewedDate": null,
      "Event": null,
      "Score": 0,
      "CreateDate": "2016-11-22T00:14:41.47-06:00",
      "UpdateDate": "2020-12-23T10:41:00.177-06:00",
      "CreateAccountId": 0,
      "UpdateAccountId": 17690,
      "SentDate": "2016-09-27T09:51:16.623-05:00",
      "Medium": "Medium",
      "ScoreText": "0",
      "ProspectInterestId": 1,
      "IsActive": true,
      "StagingLeadId": null,
      "DealerDistance": null,
      "DealerDistanceMiles": null,
      "IsQualified": true,
      "FollowUpStatusCode": "Contacted",
      "PurchaseStatusCode": "Unknown",
      "LeadTypeCode": "LeadType",
      "LeadCategoryCode": "LeadCategory",
      "LeadSourceCode": "LeadSource",
      "LeadCampaignCode": null,
      "LeadStatusCode": "Pending",
      "Customs": {
        "BuyTimeFrame": null,
        "Comment": null
      },
      "Metadata": {}
    },
    {
      "Id": 111978,
      "ExternalId": "1484059",
      "LeadUid": "eef2deaf-6a7c-475e-bf1a-e1afcfbc5eeb",
      "ProspectId": 88048,
      "DealerId": 571,
      "ProductId": 6256,
      "LeadDate": "2016-09-27T09:49:32-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-09-27T09:51:16.8-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": "LeadSource",
      "LeadCampaignCode": null,
      "LeadStatusCode": "Pending",
      "Customs": {
        "BuyTimeFrame": null,
        "Comment": null
      },
      "Metadata": {}
    }
  ]
}