Modern CRM with benefits
Free trial
System Status

API Introduction

Introduction

The Solve360 External Application Programming Interface or “API” provides clients who have access to some basic programming experience the ability to add, edit, delete and report on data in their Solve360 accounts without having to go through the Solve360 web interface. With the API, you can integrate Solve360 with your web site and other applications you use and create some pretty spiffy custom reports. This level of customization is provided so you can meet your team’s specific needs and automate as much of your work flow as possible. The API is probably easier to use and way cooler than you might originally think. It's also quite powerful; you’ll be working with some of the same tools that we use here everyday. The possibilities are only limited by your imagination.

Authentication

Your code will authenticate to the API as a real Solve360 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 is enabled on the Workspace, My Account, API Token page and is different for each user account.

API Token

Often when authenticating using HTTP Basic Authentication (the method we use) you will be prompted for a username and password. In these cases you would enter the user account’s email address as the username and the API Token as the password.

Just like your user account's password your API Token provides unlimited access to your account so be very diligent in keeping it secret and remember that the API Token can be removed or value reset at any time from the same page you first activated it.

Giving it a Spin

Point your web browser at https://secure.solve360.com/contacts and when prompted to authenticate enter a valid Solve360 user account's email address and corresponding API Token. After authenticating the server should return a list of all contacts that user account has access to in a machine readable format called XML. Not so hard eh?! Maybe to easy to be convincing so lets move on to a real-world example...

Creating a new contact in Solve360 directly from your website’s “Contact Us” form

Lets start by creating a simple web form to capture the data from the website visitor.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
<
html>
  <
head>
    <
meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <
style type="text/css">
      
labelinputtextarea { displayblockfloatleftwidth150pxmargin5px}
      label { clear
lefttext-alignright}
      input[type
="submit"] { width60pxmargin10px 0 0 165pxclearleft}
    
</style>
  </
head>
  <
body>
    <
h2>Contact Us</h2>
    <!-- 
REQUIRED Edit with the filename of the script if different than the example -->
    <
form action="Solve360ContactSave.php" method="GET">
      <
label>First name (required)</label> <input type="text" name="firstname" value="" />
      <
label>Last Name</label> <input type="text" name="lastname" value="" />
      <
label>Job title</label> <input type="text" name="jobtitle" value="" />
      <
label>Business email</label> <input type="text" name="businessemail" value="" />
      <
label>Note</label> <textarea name="note" cols="4" rows="4"></textarea>
      <
input type="submit" value="Save" />
    </
form>
  </
body>
</
html

http://yourServer/Solve360ContactForm.html

Now lets setup the script that will receive the completed form from the website visitor and save the information into Solve360. The good news is we've already done most of the work for you. You only need to edit two lines noted by the word REQUIRED with your own account information. Everything else stays the same. This file contain your API Token so it needs to be secure i.e. not readable by visitors. Note to the inclined: We've chosen the to use only native PHP functions for this example so clients don't need to worry about installing special libraries on their server. You may prefer to use CURL and send data in XML format.

<?php

    
// version 2.0

    // All placeholders such as {ownership}, {categoryId}, {templateId} should
    // be replaced with real values without the {} brackets

    // REQUIRED Edit with your email address
    
define('USER''xxxxxxxx@xxxxxxxx.com');
    
// REQUIRED Edit with token, Workspace > My Account > API Reference > API Token                             
    
define('TOKEN''xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');  
    
    
// Get request data
    
$requestData = array();
    
parse_str($_SERVER['QUERY_STRING']$requestData);
    
    
// Configure service gateway object
    
require 'Solve360Service.php';
    
$solve360Service = new Solve360Service(USERTOKEN);
    
    
//
    // Adding the contact
    //
    
    
$contactData = array(
        
'firstname'     => $requestData['firstname'],
        
'lastname'      => $requestData['lastname'],
        
'jobtitle'      => $requestData['jobtitle'],
        
'businessemail' => $requestData['businessemail'],
        
        
// OPTION Apply category tag(s) and set the owner for the contact to a group
        // You will find a list of IDs for your tags, groups and users in Workspace > My Account > API Reference
        // To enable this option, uncomment the following:

        /*        
        // Specify a different ownership i.e. share the item
        'ownership'     => {ownership},

        // Add categories
        'categories'    => array(
            'add' => array('category' => array({categoryId},{categoryId}))
        ),
        */        
        
    
);
    
    
$contact $solve360Service->addContact($contactData);
    
    if (isset(
$contact->errors)) {
        
// Mail yourself if errors occur  
        
mail(
            
USER
            
'Error while adding contact to Solve360'
            
'Error: ' $contact->errors->asXml()
        );
        die (
'System error');
    
else {
        
// Get new contact params from the response
        
$contactName = (string) $contact->item->name;
        
$contactId   = (integer) $contact->item->id;
        
        
// Mail yourself the result
        
mail(
            
USER
            
'New contact added to Solve360'
            
'New contact "' $contactName '" with id ' $contactId ' was added to Solve360'
        
);
    
}
    
    
//
    // OPTION Adding a activity 
    //
    
    /*
     * You can attach an activity to the contact you just created
     * This example creates a Note, to enable this feature just uncomment the following request
     */    
    
    /*    
    // Preparing data for the note
    $noteData = array(
        'details' => nl2br($requestData['note'])
    );

    $note = $solve360Service->addActivity($contactId, 'note', $noteData);
    
    // Mail yourself the result
    mail(
        USER, 
        'Note was added to "' . $contactName . '" contact in Solve360',
        'Note with id ' . $note->id . ' was added to the contact with id ' . $contactId
    );
    // End of adding note activity
    */
 
    //
    // OPTION Inserting a template of activities
    //
    
    /*
     * You can also insert a template directly into the contact you just created
     * You will find a list of IDs for your templates in Workspace > My Account > API Reference
     * To enable this feature just uncomment the following request
     */

    /*
    // Start of template request
    $templateId = {templateId};
    $template = $solve360Service->addActivity($contactId, 'template', array('templateid' => $templateId));
        
    // Mail yourself the result
    mail(
        USER, 
        'Template was added to "' . $contactName . '" contact in Solve360',
        'Template with id ' . $templateId . ' was added to the contact with id ' . $contactId
    );
    // End of template request
    */

?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<
html>
<
head>
<
meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</
head>
<
body>
<
h2>Result</h2>
<
p>Thank you, <b><?php echo $contactName ?></b></p>
<
p>Your data was successfully saved.</p>
</
body>
</
html

http://yourServer/Solve360ContactSave.php

To simplify the configuration we've provided a small script called Solve360Service.php which contains commonly used functions. It's required and included in the zip file below.

Lets test it out! Download Solve360Example.zip, extract the files from the ZIP file, make the necessary configuration changes described above, then upload the three files to your web server.

Open http://yourServer/Solve360ContactForm.html, fill in the values and click Save. If the test worked as expected you will see a response page which would be look like:

Thank you{firstName} {lastName}
Your data was successfully saved

If the response was successful you just created a contact so login to Solve360 and enjoy the result of your work. If there were any errors with the transaction, for example posting nonexistent fields to the system, you would receive information about them between tags in the response.

What's next? Try expanding on this example by adding additional fields to your form and enabling the category tags option in the ContactSave.php script above. To help you get going quickly lists of all Field Names, Category Tag IDs and Ownership IDs specific to your organization are provided within your account under: Workspace, My Account, API Reference.

Conventions used in the External API Documentation

Content that has been elided for brevity: ...

Any text that should be replaced by your own data: {text}

Reading Data Using the API

The API has two types of actions for reading data: List and Show. List returns a collection (e.g. a list of contacts) and Show returns a single record (e.g. all information related to a specific contact). These actions are done through the GET verb, which also means that they're easily explorable through a browser. We recommend using Firefox for this as it's renders the XML response in easy-to-read format. The response to a successful read is "HTTP/1.1 200 OK".

Writing Data Using the API

Creating, updating, and deleting items through the API is almost as simple as reading, but you can't explore it easily through the browser. We recommend using CURL to evaluate the methods first. It's a very easy way to explore the API and 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".

The response to a successful creation is status code "HTTP/1.1 201 Created". 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. new Id and created date.

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

Finally, you can delete items using the DELETE verb. Here you don't need to pass the content-type header because you're not sending any data. The response to a successful delete is "HTTP/1.1 200 OK".

Dealing With Errors

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

  • 400 Bad Request: The request was invalid. An accompanying error message will explain why. This is the status code will be returned during rate limiting.
  • 401 Not Authorized: Authentication credentials were missing, incorrect, or the authenticated user does not have access to make this request.
  • 403 Forbidden: The request is understood, but it has been refused. An accompanying error message will explain why.
  • 404 Not Found: The URI requested is invalid or the resource requested, such as a contact, does not exists.
  • 406 Not Acceptable: Returned by the Search API when an invalid format is specified in the request.
  • 500 Internal Server Error: Something is broken on our end. Please contact our support team to investigate.

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-Limit11/12000 

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.