List Item OData API

Overview

The List Item OData API provides a way to retrieve, create, and update list item information. List items are defined as the records in a list and will typically have email address and personal information for each record. It has multiple filter and expand options, allowing you to get all the lists the specific record is in as well

This is an OData endpoint and it supports 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 request for patching was successful. 
  • 400 (Bad Request). The request is invalid.
  • 401 (Unauthorized). The token is missing, invalid, or expired.
  • 404 (Not Found). The list was not able to be found.
  • 500 (Internal Server Error). The request was malformed, the list item given in the request did not exist, or some other unspecified error occurred when attempting to retrieve information.

Authentication

The List Item 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, POST and PATCH. 

Endpoint for GET

GET https://@{{baseurl}}.aimbase.com/Odata/V2/ListItem

Endpoint for POST

POST https://@{{baseurl}}.aimbase.com/Odata/V2/ListItem

Endpoint for PATCH

PATCH https://@{{baseurl}}.aimbase.com/Odata/V2/ListItem

List OData Data Schema 

The information below will be returned in a GET, sent in a POST, or updated via PATCH. 

List Item Fields 

Name

Editable

Values

Description

Id
Integer The Aimbase ID of the list item.
ListId X Integer The list ID the list item is in.
FirstName X String The list item's first name.
LastName X String The list item's last name.
Email X String The list item's email.
Address1 X String The list item's address row one.
Address2 X String The list item's address row two.
City X String The city of the list item.
State X String The state of the list item (abbreviation)
PostalCode X String The postal code of the list item.
County X String The county of the list item.
CountryCode X String The ISO country code of the list item.
DealerId X Integer The list item's dealer ID (only accepts values already in Aimbase)
DealerName X String The list item's dealer name. If entered, this must match what is in Aimbase.
DealerNumber X String The list item's dealer number. If entered, this must match what is in Aimbase. 
DealerAddress1
String The dealer's address row one.
DealerAddress2
String The dealer's address row two.
DealerCity
String The dealer's city.
DealerState
String The dealer's state.
DealerPostalCode
String The dealer's postal code.
DealerCounty
String The county of the dealer.
DealerCountryCode
String The dealer's ISO country code.
ProductCode X String The product code the list item is interested in. If entered, this must match what is in Aimbase. 
ProductName X String The name of the product the list item is interested in. If entered, this must match what is in Aimbase. 
ProductModelYear X Integer The product model year the list item is interested in.
ProductTypeName X String The product type name of the product the list item is interested in.
BrandName X String The name of the brand for the product the list item is interested in.
ProspectUid X Guid If matched to a prospect, the prospect UID for the prospect that is tied to the list item.
ProspectId X Integer If matched to a prospect, this is the prospect ID for the prospect tied to the list item.
OwnerId X Integer If matched to an owner, this is the owner ID for the owner tied to the list item.
IsManuallyAdded X Boolean This field indicates if the list item was manually or systematically added.
IsActive X Boolean This field indicates if the list item is still active within the list.
IsCommunicationOptIn
Boolean This field indicates if the list item has explicitly opted in.
CommunicationOptInIpAddress
String This field indicates the IP address the list item opted in from. It will only be filled out if IsCommunicationOptIn is Yes.
CommunicationOptInDate
DateTimeOffset This field indicates the date the user opted in. It will only be filled out if IsCommunicationOptIn is Yes. 
CommunicationOptInSource
String This field indicates the source the user opted in from. It will only be filled out if IsCommunicationOptIn is Yes. 
Source X String This indicates the source of the list item.
Type X String This indicates the type of the list item.
CompanyName X String If you use B2B, this will show the company the list item belongs to.
CompanyExternalId X String If you use B2B, this will show the external ID of the company the list item belongs to. 


Expand Options

The information of the lists are not included by default, but you can expand the list object to get that information. When you expand, you will get additional fields related to the list that the list items are members of. 

Field Name 

Editable

Format 

Description 

Id 


 Integer

The list's identifier.

Code
String The list's code in Aimbase.
Name
String The list's name in Aimbase.
Description
String The description of the list in Aimbase.
Count
Integer The count of members in the list. 

Sample Queries

Get List Based on ID

GET http://@{{baseurl}}.aimbase.com/Odata/V2/ListItem(1) HTTP/1.1

Get a List Item Based on ID and Expand List

GET http://@{{baseurl}}.aimbase.com/Odata/V2/ListItem(1)?$expand=List HTTP/1.1

Create a List Item

POST https://@{{baseurl}}.aimbase.com/Odata/V2/ListItem HTTP/1.1
Content-Type: application/json
Authenticate: Avala-Api @{{token}}


{
      "Id": 0,
      "ListId": 25,
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "johndoe@gmail.com",
      "Address1": "249 Mossy way",
      "Address2": null,
      "City": "Bravo",
      "State": "NC",
      "PostalCode": "27789",
      "County": "Beaufort",
      "CountryCode": "US",
      "DealerId": null,
      "DealerName": "",
      "DealerNumber": "",
      "DealerAddress1": ".",
      "DealerAddress2": "",
      "DealerCity": "",
      "DealerState": "",
      "DealerPostalCode": "",
      "DealerCounty": null,
      "DealerCountryCode": "",
      "ProductCode": "",
      "ProductName": "",
      "ProductModelYear": null,
      "ProductTypeName": "",
      "BrandName": "",
      "ProspectUid": "2c4be13e-0135-4256-b128-b39cb68463ff",
      "ProspectId": null,
      "OwnerId": null,
      "IsManuallyAdded": true,
      "IsActive": true,
      "IsCommunicationOptIn": null,
      "CommunicationOptInIpAddress": null,
      "CommunicationOptInDate": null,
      "CommunicationOptInSource": null,
      "Source": null,
      "Type": null,
      "CompanyName": null,
      "CompanyExternalId": null
    }

Update a List Item

PATCH https://@{{baseurl}}.aimbase.com/Odata/V2/ListItem(530848) HTTP/1.1
Content-Type: application/json
Authenticate: Avala-Api @{{token}}


{
      "Id": 530848,
      "ListId": 25,
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "johndoe_2@gmail.com",
      "Address1": "249 Mossy way",
      "Address2": null,
      "City": "Bravo",
      "State": "NC",
      "PostalCode": "27789",
      "County": "Beaufort",
      "CountryCode": "US",
      "DealerId": null,
      "DealerName": "",
      "DealerNumber": "",
      "DealerAddress1": ".",
      "DealerAddress2": "",
      "DealerCity": "",
      "DealerState": "",
      "DealerPostalCode": "",
      "DealerCounty": null,
      "DealerCountryCode": "",
      "ProductCode": "",
      "ProductName": "",
      "ProductModelYear": null,
      "ProductTypeName": "",
      "BrandName": "",
      "ProspectUid": "2c4be13e-0135-4256-b128-b39cb68463ff",
      "ProspectId": null,
      "OwnerId": null,
      "IsManuallyAdded": true,
      "IsActive": true,
      "IsCommunicationOptIn": null,
      "CommunicationOptInIpAddress": null,
      "CommunicationOptInDate": null,
      "CommunicationOptInSource": null,
      "Source": null,
      "Type": null,
      "CompanyName": null,
      "CompanyExternalId": null
    }


Sample Responses

After Creating or Updating a List Item

{
  "@odata.context": "https://{baseurl}.aimbase.com/odata/V2/$metadata#ListItem/$entity",
  "Id": 530848,
  "ListId": 25,
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "johndoe@gmail.com",
  "Address1": "249 Mossy way",
  "Address2": null,
  "City": "Bravo",
  "State": "NC",
  "PostalCode": "27789",
  "County": "Beaufort",
  "CountryCode": "US",
  "DealerId": null,
  "DealerName": "",
  "DealerNumber": "",
  "DealerAddress1": ".",
  "DealerAddress2": "",
  "DealerCity": "",
  "DealerState": "",
  "DealerPostalCode": "",
  "DealerCounty": null,
  "DealerCountryCode": "  ",
  "ProductCode": "",
  "ProductName": "",
  "ProductModelYear": null,
  "ProductTypeName": "",
  "BrandName": "",
  "ProspectUid": "2c4be13e-0135-4256-b128-b39cb68463ff",
  "ProspectId": null,
  "OwnerId": null,
  "IsManuallyAdded": true,
  "IsActive": true,
  "IsCommunicationOptIn": null,
  "CommunicationOptInIpAddress": null,
  "CommunicationOptInDate": null,
  "CommunicationOptInSource": null,
  "Source": null,
  "Type": null,
  "CompanyName": null,
  "CompanyExternalId": null
}