API Reference
Start typing to search…

Getting Started with Ferret API

🚧

Ferret API (v2) is in BETA

Please be aware that this version is still in active development, and significant changes to the API may occur. For production use, please use the Octopus API instead.

Welcome to Ferret API!

The Ferret API is the simplest way to connect with Maximizer, whether you're customizing your CRM experience or integrating with our platform. This RESTful API is designed to simplify and streamline data interactions, making it easy to use. Let's get you set up!

🔖

Ferret API v2 is built on top of Octopus API. It enables you to start working with Maximizer in minutes! We are constantly adding new methods for your convenience. However, if you need functionality not yet available in the Ferret API, please check out the Octopus API. It shares the same domain model and offers more comprehensive functionality, although it might be more complex initially.

📘

For any questions or support, please reach out to us via Forums.

Steps to using the API

Step 1: Get authenticated

To access Ferret, you will need to obtain an access token. There are two ways to accomplish this, but we recommend starting with the first one:

  1. Create a long-living Personal Access Token (more details about PAT) within your Maximizer account:
    • Log in to your Maximizer account.
    • Click on your profile photo to open the drop-down menu.
    • Select "Personal Access Tokens" and follow the prompts to create a new PAT.
    • Enter the name of the token, choose the expiration date and click "Save".
    • Copy your token to a secure location.
  2. Authenticate by using Ferret's /authenticate endpoint:
    • You must request the VendorId and AppKey (for the cloud platform only).
    • Navigate to the Api Reference in the developer and find the Authenticate Tab under Ferret API.
    • Enter your credentials and click on "Try-it!".
    • Copy your token, but keep in mind that a regular access token will expire in 2 minutes
  3. By using OAuth2

Step 2: Get familiar with our object relationships schema

Check out our object relationships schema to identify which objects are relevant to your needs and how they relate to each other. More detailed information about our domain schema and use cases can be found in our Octopus API documentation.

Step 3: Get your data

Once you have identified the objects and fields you are interested in, you can access your data using Ferret API. Here are the key endpoints available:

  • Metadata: Provides a comprehensive list of all available fields and options for that object.

Tip: Check the metadata with ExpandFields = true to discover which fields have options. If the field's HasOption = true, then plug this field into the FieldOptions endpoint to see what the options are.

  • GetObjectByKey: Retrieve a single object by its key, specifying the fields you wish to include in the response.
  • GetListOfObjects: Retrieve all instances of a particular object in your database, specifying the fields you wish to include in the response.
  • Search: Gain more control by specifying search criteria along with the desired fields to be included in the response.
  • FieldOptions: Discover the available options for specific fields, allowing you to understand the possible values.

Tip: Make sure to include your token in the Authorization header in your requests, and specify the type of token, like this: "Bearer<ThisIsMyToken>"


HTTP Response Codes

200 OK - Ferret API has completed your request successfully.

400 Bad Request - Ferret API cannot process the request due to invalid or missing parameter values. Check the message in the response body for details, correct your request, and try again.

401 Unauthorized - Ferret API cannot authorize the request based on the provided credentials. Ensure that you have included a valid Bearer token in the request header.

408 Request Timeout - Ferret API could not complete the request within the server's allotted timeout period. Please check your request, simplify it and try again. Please, see the Request Limits section below.

429 Too Many Requests - Ferret API received an excessive number of requests from your client in a short period. To avoid exceeding the rate limit, please check the response header for the "Retry-After" time and wait until that time has elapsed before sending more requests. Please, see the Request Limits section below.

5xx Internal Server Error - Ferret API encountered an unexpected error while processing your request. Please try again later or contact support for assistance.


Pagination

To enhance performance and improve user experience, our API uses pagination for requests that return multiple results. When making GetListOfObjects and Search requests, you must specify a PageSize parameter, which is an integer between 1 and 100. In the response, if the NextPageKey is not null, copy its value into the PageKey parameter of your next request. This will fetch the next page of results. Continue this process until NextPageKey is null to retrieve all available data.


Request Limits

Both Ferret API and Octopus API enforce two types of limits to ensure better availability for our clients:

  1. Rate Limit: The number of requests allowed per minute per user. If exceeded, API responds with a 429 HTTP code.
  2. Request Duration: The maximum time allowed per request. If exceeded, API responds with a 408 HTTP code.

These limits vary by product edition:

Base Edition:

  • Rate Limit: 30 requests per minute
  • Request Duration: 10 seconds

SLE/FAE:

  • Rate Limit: 90 requests per minute
  • Request Duration: 30 seconds

Enterprise/Private Cloud:

  • Custom limits
  • Custom duration limits

Known Issues and Limitations

  • For now, Ferret API provides read-only methods. For Create, Update, and Delete operations, as well as more customized Read operations, please use our Octopus API.