API Reference
Start typing to search…

Key

  • Available Since API Version – 2.0\

Octopus API uses special strings, or Keys, to identify entries. Each entry has a unique Key which may be used to identify it when making requests to the API. Key objects contain the following properties:

  • Value - A hex-encoded string value containing the Key. Note that this value should not be used to store persistent references to Maximizer objects in an external database (see below).\

  • UID - The UID property is available in User Keys. It is a string value containing the Maximizer UserID of the User. When storing references to Maximizer users in an external database, this UID value should be used, as it is invariant for the lifetime of the user.\

  • ID - A string value containing the internal Maximizer ID of the entry. When storing a reference to a Maximizer entry in an external database, this ID in conjunction with the Number property should be used, as they are invariant for the lifetime of the entry and provide a unique reference. When migrating an existing application from one of the legacy Maximizer APIs such as MaAccess or the SQL Views, the ID will be familiar as the database ID of the entry. For example, for AbEntry objects, the ID property contains the entry's Client_Id.\

  • Number - An integer value containing the internal Maximizer ID number. When storing a reference to a Maximizer entry in an external database, this Number in conjunction with the ID property should be used, as they are invariant for the lifetime of the entry and provide a unique reference. When migrating an existing application from one of the legacy Maximizer APIs such as MaAccess or the SQL Views, the Number will be familiar as the database Number of the entry. For example, for AbEntry objects, the Number property contains the entry's Contact_Number.\

  • EntityType - An integer value identifying the type of entity to which the key belongs. Possible EntityType values include:

    • 1 - AbEntry\

    • 2 - Opportunity\

    • 3 - Campaign\

    • 5 - Case\

    • 10 - Appointment\

    • 19 - Lead\

    • 100 - Custom\

    • 101 - CustomChild\

Using Keys to Identify Entries

Whenever a new entry is created in Maximizer, it is assigned a unique Key that may be used to identify it. When you create an entry you can choose to retrieve the entry’s Key in the API response. If you wish to modify or delete an entry, you must provide the Key of the entry in your request in order to identify which entry you want to update or delete. You can also use entry Keys to search for specific entries or to search for related entries of other entity types.

Storing References to Entries

Octopus API Keys are not guaranteed to be invariant across different sessions, different servers, or different versions of the software. They should be considered to be valid only for the session in which they are retrieved and should not be used to persist references to Maximizer entries in external data stores. Instead, the ID and Number properties of the Key object, or the UID property in the case of users, should be stored whenever a persistent reference is requried to a Maximizer record, as these properties will remain invariant for the life of the object.

Using Keys to Establish Relationships

Octopus API Keys are also used to establish relationship between entries in Maximizer. In addition to the identity Key property, many entity types in the Octopus API API also have additional Key properties to indicate relationships with other entries.

For example, contact entries in Maximizer always have a parent company or individual entry to which they belong. This relationship is represented in Octopus API via the ParentKey property of the contact. When creating a new contact entry, you can specify the Key of a given company as the contact’s ParentKey to create the new contact under that company. And when reading contact entries you can identify the company or individual to which the contact belongs using the contact’s ParentKey property.

Integration with Maximizer UI APIs

Many of the Maximizer UI APIs that are used for integrating with Maximizer’s user interface provide methods for you to obtain the Keys of the current or selected entries in the Maximizer user interface. For example, the Following Grid Framework API passes the Key of the current entry in the main grid as a parameter to your custom web service.

Some Maximizer UI APIs also provide ways that you can interact with the Maximizer user interface using entry Keys. For example the MainGridUpdate API provides methods that allow you to add entries to the main Maximizer grid by passing the Keys of the entries you wish to add from a Following Tab or MenuBuilder integration.

Basic Read Request

The following example illustrates the syntax for a request for the default value of a Key in a Read method call.

Request

{
  "Key":1
}

Response

{
  "Key":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTE="
}

Detailed Read Request

The following example illustrates the syntax for a request for all properties of a Key in a Read method call.

Request

{
  "Key":{
    "Value":1,
    "EntityType":1,
    "ID":1,
    "Number":1
  }
}

Response

{
  "Key":{
    "Value":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTg=",
    "EntityType":1,
    "ID":"001002000613063671156C",
    "Number":8
  }
}

Detailed Read Request (User)

The following example illustrates the syntax for a request for all properties of a User Key in a UserRead method call.

Request

{
  "Key":{
    "Value":1,
    "UID":1
  }
}

Response

{
  "Key":{
    "Value":"VXNlcglNQVNURVI=",
    "UID":"MASTER"
  }
}

Create Request

The following example illustrates the syntax for including a Key in a Create method call.

Note that because keys are generated automatically by the Octopus API, you cannot specify a value for the key. Instead, by including a null value for the Key in your Create request, you can indicate to the API that you would like the Key of the new entry returned in the response.

Request

{
  "Key":null
}

Response

{
  "Key":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTE="
}

Update Request

The following example illustrates the syntax for including a Key in an Update method call.

Note that you cannot modify the Key of an entry. Instead, when you include the Key of an entry in an Update request, it is used to identify the entry to be updated.

Request

{
  "Key":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTE="
}

Response

{
  "Key":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTE="
}