Introduction

The Solve Application Programming Interface (API) is designed for clients with basic programming resources to integrate different websites and applications, creating a seamless workflow. This API enables users to add, edit, delete, and report on data in their Solve accounts without relying on the Solve web interface.

Preamble

The Solve External API is implemented over HTTP and is RESTful. Every item has its own URI and is manipulated in isolation.

You will normally send your Request data in XML format, but we understand JSON and form encoded data just as well. If you want to use a non-XML request format, simply set the HTTP “Content-type” header to either application/json or application/x-www-form-urlencoded. Conversely, we will normally send response data in XML form, unless you set the HTTP “Accept” header to application/json.

XML requests must be enclosed within <request></request> tags. JSON requests do not require this parameter.

To receive a response in JSON with padding (JSONP) format, simply pass a ‘callback’ parameter in the query string. For example, appending callback=myFunction to your request will result in a response body of: myFunction(…). Callbacks may only contain alphanumeric characters and underscores; any invalid characters will be stripped.

Please note, access to features and data is limited to the actual user account being used to access the API. Likewise, admin actions cannot be performed via API (i.e. granting workgroup permissions, etc.). The admin has to do this from within the main system.

You can find a list of all entity details including IDs under under: Settings > My Account > API Reference.

Unless otherwise specified, date/time is always reported in UTC and formatted according to ISO 8601. When saving date/time data, values must first be converted from local time to UTC and follow one of these formats: 2004-02-12T15:19:21+00:00 (ISO 8601), 2004-02-12 15:19:21, or just 2004-02-12.

Authentication

Your code will authenticate to the API as a real Solve user account and will have access to everything that particular account has. However, instead of logging in using the user’s password, your code will use the user’s “API Token”. The API Token can be found under Settings > My Account > API Token. Each user account has a unique API Token.

When authenticating via HTTP Basic Authentication (the method we use), you will be prompted for a username and password. Simply enter your Solve email address under username and API Token under password.

Just like your user account’s password, your API Token provides unlimited access to your account. Be very diligent in keeping it secret.

Quick test

Type out the following URL in your web browser: https://secure.solve360.com/contacts. When prompted to authenticate, enter a valid Solve user account’s email address and the corresponding API Token. After authenticating, the server should return a list of all contacts that the user’s account has access to. The data is displayed in a machine readable format called XML.

You can find a list of all Field Names, Field IDs, Category Tag IDs and Ownership IDs under: Settings > My Account > API Reference.

Conventions

Reading data

The API has two common types of actions for reading data: LIST and SHOW.

• LIST returns a collection (e.g. a list of contacts)
• SHOW returns a single record (e.g. all information related to a specific contact)

These actions are done through the GET verb. You can also view the extracted data directly on a web browser. We recommend using Firefox/Chrome, as it’s renders the XML response in easy-to-read format.

Note: A successful read response is indicated by: ”HTTP/1.1 200 OK”.

Writing data

Actions such as creating, updating, and deleting items through the API is almost as simple as reading, but are not accessible via a web browser. We recommend using cURL to evaluate the methods first, since it’s an easy way to explore the API. It’s perfect for scripts too!

When you’re creating and updating items, you’ll be sending XML into the API and including the XML content in the body of your request. If you prefer to send regular form-encoded data, just let the system know that by adding the header ”Content-type: application/x-www-form-urlencoded”.

Creating data

Creating an item is done via the POST verb. A successful create action displays a ”HTTP/1.1 201 Created” response.

You can read the URI of the new resource in the location header, which is handy if you need to refer to your newly created item. Since you can create a new item, with less than all its regular attributes, the API also returns the complete XML for the newly created item in the response e.g. the record’s new Id and created date.

Updating data

Updating an item is done through the PUT verb and against the URI of the resource you want to update. A successful update action displays a ”HTTP/1.1 200 OK” response.

Deleting data

You can delete items using the DELETE verb. In this case, you won’t need to pass the content-type header because you’re not sending any data. A successful delete action displays a ”HTTP/1.1 200 OK” response.

Dealing with errors

If a request fails, the error information is returned with the HTTP status code:

API limit

Clients may request up to 12,000 API calls every 24 hours. Most clients will never hit this threshold, but those that do will result in a reply with an error status code of 403. We encourage developers to anticipate this error, and take appropriate measures. API responses return the current app’s call limits in the response headers:

Http-X-Solve360-Api-Call-Limit: 11/12000

Note: Inserting a template of activities counts as one for the main call and one for each activity inserted.

If you’re concerned about the API limit consider integrating Webhooks into your solution.