Rollick Knowledge

Contact us

Account OData API

 

Overview

Use the Account OData API to create and manage user accounts within Aimbase. This API enables the creation and updating of accounts. After an account is established, you can utilize additional functions to set data permissions for the account. These permissions determine which data the user is able to access within Aimbase.

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)
  • 400 (Bad Request)
  • 400 (Bad Request)
  • 500 (Internal Server Error)

 

Authentication

The Account OData API requires authentication. 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}

 

Account Schema

Field Name  Required Max Length Description 
Name X 50 Username for the account.
Email X 256 Email address associated with the account.
AccountRoleCode X 64

This is the account's role. Options are as follows:

  1. Corporate
  2. Brand
  3. Dealer

Account Roles & Account Types

Account roles must correspond with specific account types. Ensure alignment between chosen roles and types. Refer to the table below.

Account Role Account Type
Corporate Corporate Admin
Corporate Corporate User
Brand Regional Sales Admin
Brand Regional Sales User
Brand Division Admin
Brand Division User
Brand Brand Admin
Brand Brand User
Dealer Dealer Admin
Dealer Dealer User
Dealer Dealer Group Admin
Dealer Dealer Group User
 

 
AccountTypeName X 100

This is the account's type. Options are as follows:

  1. Brand Admin
  2. Brand User
  3. Corporate Admin
  4. Corporate User
  5. Dealer Admin
  6. Dealer Group Admin
  7. Dealer Group User
  8. Dealer User
  9. Division Admin
  10. Division User
  11. Regional Sales Admin
  12. Regional Sales User
SsoProviderInformationName X 50

This field defines the Single Sign-On (SSO) context for the user. It specifies whether users can authenticate using native passwords, exclusively through SSO, or both. This setting ensures adherence to specified security policies by regulating authentication methods.

The values for this field will be provided by Rollick.
FirstName   80 Account users first name.
LastName   80 Account users last name.
ExternalId   128 Identifier that can be assigned during account creation to maintain synchronization between Aimbase and external systems.
Address1   1024 Account user's address.
Address2   1024 Account user's address.
City   256 Account user's city.
StateProvinceCode   512 Account user's state/province.
PostalCode   50 Account user's postal code.
CountryCode   512 Account user's country code.
IsActive X   This field is a boolean and accepts true/false.
IsApproved X   This field is a boolean and accepts true/false.
IsLocked X   This field is a boolean and accepts true/false.

 

Account Data Permission Schema

Field Name  Required Description 
ManufacturerCode X Specifies the manufacturer you want to associate with the account user. This is the highest level hierarchy record in your Aimbase install. These values will be provided to you by Rollick.
BrandGroupCode   Specifies the brand group you want to associate with the account user. These values will be provided to you by Rollick.
DealerNumber X This is the dealer number identifier for dealers in Aimbase. This number can be found via the Dealer Search API or by visiting the dealer page in Aimbase.
RegionCode   Specifies the geographical region you want to associate with the account user. These values will be provided to you by Rollick.
TerritoryCode   Specifies the geographical territory you want to associate with the account user. These values will be provided to you by Rollick.

 

Use Cases & Examples

 

Retrieving Account Details 

This section describes how to retrieve account data using the GET method with the Account OData API. Example requests and responses are provided below for guidance.

Endpoint

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

Examples

Retrieving all accounts

Request

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

Response

{
  "@odata.context": "https://example.aimbase.com/odata/V2/$metadata#Accounts",
  "value": [
    {
      "Id": 291,
      "Name": "johndoe",
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "johndoe@example.com",
      "AccountUid": "319fc420-d446-1172-9ce0-f0dd01198896",
      "ExternalId": "371289367892",
      "AccountTypeName": "Dealer Admin",
      "AccountRoleCode": "Dealer",
      "SsoProviderInformationName": "Example",
      "Address1": "123 Main St.",
      "Address2": "Suite 100",
      "City": "Denver",
      "PostalCode": "80212",
      "StateProvinceCode": "CO",
      "CountryCode": "US",
      "IsActive": true,
      "IsApproved": true,
      "IsLocked": false,
      "CreateDate": "2024-04-15T10:59:23.3535886-05:00",
      "UpdateDate": "2024-04-15T10:59:23.3535886-05:00"
    },
    {
      "Id": 291,
      "Name": "johndoe",
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "johndoe@example.com",
      "AccountUid": "319fc214-dcf6-1172-9ce0-f0dd01790538",
      "ExternalId": "191817161514131",
      "AccountTypeName": "Dealer Admin",
      "AccountRoleCode": "Dealer",
      "SsoProviderInformationName": "Example",
      "Address1": "123 Main St.",
      "Address2": "Suite 100",
      "City": "Denver",
      "PostalCode": "80212",
      "StateProvinceCode": "CO",
      "CountryCode": "US",
      "IsActive": true,
      "IsApproved": true,
      "IsLocked": false,
      "CreateDate": "2024-04-15T10:59:23.3535886-05:00",
      "UpdateDate": "2024-04-15T10:59:23.3535886-05:00"
    },

}
 
 

Retrieving single account by AccountUid

Request

GET http://{baseurl}/odata/V2/Accounts?$filter=(AccountUid eq da064328-7653-48a7-bb93-9c6f9222108c)

Response

{
  "@odata.context": "https://example.aimbase.com/odata/V2/$metadata#Accounts",
  "value": [
    {
      "Id": 291,
      "Name": "johndoe",
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "johndoe@example.com",
      "AccountUid": "319fc420-d446-1172-9ce0-f0dd01198896",
      "ExternalId": "371289367892",
      "AccountTypeName": "Dealer Admin",
      "AccountRoleCode": "Dealer",
      "SsoProviderInformationName": "Example",
      "Address1": "123 Main St.",
      "Address2": "Suite 100",
      "City": "Denver",
      "PostalCode": "80212",
      "StateProvinceCode": "CO",
      "CountryCode": "US",
      "IsActive": true,
      "IsApproved": true,
      "IsLocked": false,
      "CreateDate": "2024-04-15T10:59:23.3535886-05:00",
      "UpdateDate": "2024-04-15T10:59:23.3535886-05:00"
    },
 }
 
 

Retrieving single account by AccountId

Request

GET http://{baseurl}/odata/V2/Accounts(2384)

Response

{
  "@odata.context": "https://example.aimbase.com/odata/V2/$metadata#Accounts",
  "value": [
    {
      "Id": 291,
      "Name": "johndoe",
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "johndoe@example.com",
      "AccountUid": "319fc420-d446-1172-9ce0-f0dd01198896",
      "ExternalId": "371289367892",
      "AccountTypeName": "Dealer Admin",
      "AccountRoleCode": "Dealer",
      "SsoProviderInformationName": "Example",
      "Address1": "123 Main St.",
      "Address2": "Suite 100",
      "City": "Denver",
      "PostalCode": "80212",
      "StateProvinceCode": "CO",
      "CountryCode": "US",
      "IsActive": true,
      "IsApproved": true,
      "IsLocked": false,
      "CreateDate": "2024-04-15T10:59:23.3535886-05:00",
      "UpdateDate": "2024-04-15T10:59:23.3535886-05:00"
    },
 }
 
 

 

Creating Accounts

This section explains how to create new accounts using the POST method with the Account OData API in Aimbase. Example requests and responses are included below for guidance.

Endpoint

POST https://{baseurl}/odata/V2/Accounts

Example

Create a new account

Request

POST https://{baseurl}/odata/V2/Accounts
Content-Type: application/json
Authenticate: Avala-Api {AuthenticationToken}
{
    "Name": "johndoe",
    "Email": "johndoe@example.com",
    "AccountTypeName": "Dealer Admin",
    "AccountRoleCode": "Dealer",
    "SsoProviderInformationName": "Example",
    "FirstName": "John",
    "LastName": "Doe",
    "ExternalId": "191817161514131",
    "Address1": "123 Main St.",
    "Address2": "Suite 100",
    "City": "Denver",
    "StateProvinceCode": "CO",
    "PostalCode": "80212",
    "CountryCode": "US",
    "IsActive": true,
    "IsApproved": true,
    "IsLocked": false
}

Response

{
  "@odata.context": "https://example.aimbase.com/odata/V2/$metadata#Accounts/$entity",
  "Id": 291,
  "Name": "johndoe",
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "johndoe@example.com",
  "AccountUid": "319fc214-dcf6-1172-9ce0-f0dd01790538",
  "ExternalId": "191817161514131",
  "AccountTypeName": "Dealer Admin",
  "AccountRoleCode": "Dealer",
  "SsoProviderInformationName": "Example",
  "Address1": "123 Main St.",
  "Address2": "Suite 100",
  "City": "Denver",
  "PostalCode": "80212",
  "StateProvinceCode": "CO",
  "CountryCode": "US",
  "IsActive": true,
  "IsApproved": true,
  "IsLocked": false,
  "CreateDate": "2024-04-15T10:59:23.3535886-05:00",
  "UpdateDate": "2024-04-15T10:59:23.3535886-05:00"
}
 
 

 

Updating Accounts

This section describes how to update existing accounts using the PATCH method with the Account OData API. Example requests and responses are provided below for guidance.

Endpoint

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

Example

Update an existing account

An account must have data permissions assigned to be considered 'Complete' and editable in Aimbase.

 

Request

PATCH https://{baseurl}/odata/V2/Accounts(2384)
Content-Type: application/json
Authenticate: Avala-Api {AuthenticationToken}
{
    "IsActive": false

Request

HTTP/1.1 204 No Content
 
 

 

Adding account data permissions

This section outlines how to assign data permissions to an account, which determines the scope of data accessible to the account user within Aimbase. Use the full version of this function when the complete hierarchy path of the account user is known. If the hierarchy path is unknown, the partial function can be used by providing only the manufacturer and dealer information; Aimbase will automatically complete the remaining hierarchy details.

Required: Data Permissions

To complete the setup of an Aimbase account and enable user access, it is mandatory to assign data permissions. Without these permissions, users will not have the ability to log into the system.

 

 

Data Permission Hierarchy Function (full hierarchy)

Endpoint

POST https://{baseurl}.aimbase.com/odata/V2/Accounts({AccountId})/AimbaseOData.AccountMethods.SetDataPermissions HTTP/1.1
Content-Type: application/json;odata.metadata=full
Authenticate: Avala-Api {AuthenticationToken}

{
    "Permissions": [
        {
            "OrganizationalHierarchyPath": "ORG/{ManufacturerCode}/{BrandGroupCode}/{DealerNumber}",
            "GeographicalHierarchyPath": "GEO/{ManufacturerCode}/{RegionCode}/{TerritoryCode}/{DealerNumber}"
        }
    ]
}

Example

Adding data permissions using full hierarchy path

Request

POST https://{baseurl}.aimbase.com/odata/V2/Accounts({AccountId})/AimbaseOData.AccountMethods.SetDataPermissions HTTP/1.1
Content-Type: application/json;odata.metadata=full
Authenticate: Avala-Api {AuthenticationToken}

{
    "Permissions": [
        {
            "OrganizationalHierarchyPath": "ORG/ROL/LIC/Dealer123",
            "GeographicalHierarchyPath": "GEO/ROL/US/SE/Dealer123"
        }
    ]
}

Response (Success)

HTTP/1.1 200 OK

Response (Failure)


{
  "error": {
    "code": "",
    "message": "Geographical hierarchy with path: GEO/ROL/US/SE/Dealer123 does not exist."
  }
}
 
 

 

Data Permission Hierarchy Function (partial hierarchy) 

Endpoint

POST http://{baseurl}.aimbase.com//odata/V2/Accounts({AccountId})/AimbaseOData.AccountMethods.SetDataPermissionsByCode HTTP/1.1
Content-Type: application/json;odata.metadata=full
Authenticate: Avala-Api {AuthenticationToken}

{
  "Permissions": [
    {
      "Type": "Manufacturer",
      "Code": "{ManufacturerCode}"
    },
    {
      "Type": "Dealer",
      "Code": "{DealerNumber}"
    }
  ]
}

Example

Adding data permissions using partial hierarchy path

Request

{
  "Permissions": [
    {
      "Type": "Manufacturer",
      "Code": "ROL"
    },
    {
      "Type": "Dealer",
      "Code": "TestDealer1"
    }
  ]
}

Response (Success)

HTTP/1.1 200 OK

Response (Failure)

{
  "error": {
    "code": "",
    "message": "The following manufacturers do not exist or are not accessible: ROL."
  }
}
 
 

 

 

 

Related Articles

Sign On Account Web Service Specification

Overview  Sign-On Account   This service will allow  existing  users to pass dire...

Account Search API

Overview  This API is used to search for existing accounts by account name, email...

Sign On Dealership Web Service Specification

Overview Account Sign-On Dealership   This service will allow users to pass direc...