Interacting with Innovate API

Planbox Innovate (formerly known as Idealink) provides a comprehensive REST-like web API which lets you do anything. We believe so strongly in an open API that we built Idealink itself around the API. Anything the web application can do, you can do (better). Using the Planbox Innovate client SDK (a strongly-typed .NET class library), you can easily interact with the API with full code completion and documentation at your fingertips.

API overview

Structure

Planbox Innovate's API consists of multiple distinct endpoints (like the user endpoint or authentication endpoint) which accept standard HTTP GETPOST, and DELETE requests. For example, you can retrieve a list of users in Planbox Innovate by calling GET /latest/users, or submit an idea by calling POST /latest/ideas with the idea. These are called REST methods because they conform to the standard REST philosophy. Some endpoints also provide special ad-hoc methods; for example, you can retrieve the current authenticated user by calling GET /latest/users.current.

All methods are included in the client SDK, so you don't need to research the API structure or available endpoints. For example, you can log in to Planbox Innovate and invite a user in three lines (with auto-completion):


Content format

The API accepts and returns all content in the JSON format. The content serialization is handled for you by the client SDK.

Authentication

You can authenticate to the Planbox Innovate API by using your secret authentication key, an encrypted token which is unique to each user. To view your secret key, view your profile (click your name in the top-right corner) and click the Security tab. (You shouldn't share this key with anyone.)

To authenticate without using the SDK, set the HTTP Authorization header to "SecretKey YOUR_SECRET_KEY". To authenticate using the Idealink SDK:

var client = new IdealinkClient(...);client.SetAuthentication(IdealinkAuthorizationHeader.SecretKey, "your-secret-key");

The Planbox Innovate API also supports the same authentication methods used by the web UI. For example, your browser is automatically authenticated to the API using your web session cookies. If you just want to perform a quick API query, you can access the API directly in your browser or use a browser extension like Chrome's Postman extension which will be authenticated by your cookies.

Error-handling

Your Planbox Innovate API query might return an error — for example, you might not be authenticated or you might have requested a resource that doesn't exist. This is automatically handled by the client SDK, which will throw an IdealinkApiException with a detailed error message, or a more specific subclass like ResourceNotFoundException.

Frequently-asked questions

Getting the client SDK

The Planbox Innovate client SDK is in early development. It's functional and used by Planbox Innovate itself, but many endpoints still require knowledge of the underlying API structure. Furthermore, the API structure is not considered public so it's still subject to change (though this is mitigated by the SDK, which provides compile-time validation).

The client SDK is available on request to enterprise clients — let us know what you need it for and we'll make sure the relevant endpoints are included.

Interacting with Planbox Innovate API directly (without the client SDK)

You can interact with the API using standard HTTP requests since it's based on open web standards. (In fact, that's what the client SDK does under the hood.)

We don't officially support this yet — not because it's discouraged, but just because we're focusing on the rollout of the client SDK. We have long-term plans to provide complete API documentation for users who want to access the API directly.

Feedback and Knowledge Base