Circle Cloud API Help

Introduction

The Circle Application Programming Interface (API) is available in the form of REST API. This technology is recommended for use when developing new, custom-made applications that are based on the Circle platform. For example, you can use this API to create Web-to-Print applications, cross-media applications, etc.

General Information

Cloud APIs are accessible using HTTPS protocol only.

APIs receive and return JSON objects. The "Content-Type" header with the "application/json" value should be added to all requests.

In case of an error, all Cloud APIs throw an ExceptionModel exception, resulting in a "Bad Request" (400) HTTP error received by the client.

Authentication

Each Cloud API receives a Circle security token that is used by Circle for authentication and authorization of the caller. The security token is a string generated by the login API: POST v1/system/login. The login API receives the Circle user's name and password, and returns a Circle security token.

The API caller provides the generated security token to other APIs using one of the following options:

• In the HTTP request header:

Header name: Authorization

Header value: Circle [security_token]

• In the query string as part of the URL:

Parameter name: securityToken

Parameter value: [security_token]

The security token can be used for calling APIs for one hour only. After this period, a SecurityTokenExpired error is thrown by all APIs that receive the expired security token.

When this occurs, the website/application has two options:

• Create a new security token using the login API. This means that the application/website requests the user to provide Circle credentials again.

• Renew the security token using the renew login API: POST v1/system/renewlogin.

This API receives a security token and returns a new one. The API can be called three hours after login creation, after which an InvalidCredentials error is thrown by any API that receives the expired security token. The renew login option enables the website/application not to store the user's Circle credentials and not to ask for credentials very often.

The website/application can always call the logout API: POST v1/system/logout. This API receives a security token and releases it. As a result, all APIs that receive a security token that was released throw an InvalidCredentials error.

More API Resources

For API training as well as the custom SMS provider API for analytics, see Circle API training.
Note that the use of the Circle API is restricted to customers who purchased the uProduce API license.

---