Ubersmith was designed to be incredibly powerful out of the box, but sometimes, our customers encounter unique scenarios or use cases which require something extra. Fortunately, Ubersmith is extremely extensible via the API, our module framework, and event triggers. Let’s explore the first topic and demonstrate how you can get started with our API right away.
Ubersmith’s API is a powerful tool which allows users to extend our product’s default behavior. Your team can leverage the API to automatically deploy services, generate custom reports, perform batch modification of objects, and just about anything else you can imagine. There are many tasks, particularly repetitive ones, which are much more approachable via the API than in the UI. The API functionality is also mirrored within the plugin system through our SDK, so any plugins you develop can leverage the power of our API without the added overhead of making HTTP requests.
Let’s get started.
First, please clone (or download) the API Examples repository via GitHub and put it on the machine you wish to use. Log in to your Ubersmith instance. Edit the user you wish to give access to by going to Settings -> Users and selecting one, or go to your user preferences to edit yourself. Look for the API Tokens section, and click Edit to add a new token.
Type a name for the token, and click Generate Token. You now have a credential to access the API; please make note of the Token string itself.
Now, return to where you’ve copied the repository. Define your configuration in the config.inc.php file. Below is a detailed description of each of the fields in this configuration file:
domain: Full URL with protocol like
http:// or
https:// representing the publicly-accessible server on which Ubersmith is installed.
For example: https://subdomain.domain.com
api_client_path: Path to Ubersmith API Client. You can use the default value, provided that you have cloned the GitHub repository and have not changed the location of the class.uber_api_client.php file.
api_username: API Username. Please note that this is not the name you have given the token upon creation. This is the Ubersmith login username for the user which needs API access.
api_token: A 32-character unique hash that is generated when a new API token is added as described above. You can copy this from your Ubersmith instance and paste it into this file. Please ensure that you haven’t added any spaces or other characters to this token string.
Please take a moment to refer to our API documentation for a complete list of methods, parameters, and expected output before continuing. You’ll want to look at individual methods described later on.
The first action you should take is to use the test script test.phpto see if you can successfully connect to the API. You can execute any of the included PHP files on the command line, or via your browser. If you do wish to execute these scripts via the browser, you’ll have better results by viewing the source code. This is because the output is pure text (not HTML), and it’s more easily visualized in raw format.
Once you have the test script up and running, you will be able to use all of the other scripts as well, since they also refer to the existing configuration file. Let’s take a look at the Client Import script client_import.php in detail to get more acquainted with how this works. After the first few lines describing its purpose, a few more more error configuration, and a line including the above-mentioned configuration file, we get right to the point. This section augments the inherited configuration with parameters for importing clients:
You can format this array however you prefer, just make sure that no keys are named the same thing as existing configuration keys. The first two values are where you can define a Salesperson and Relationship for the imported clients, if you wish. You can find this ID via the Ubersmith UI, or just leave them as they are.
Next, we’ll define the field mapping for your CSV file. The file you provide will have rows and columns; each column is represented by an index, beginning with 0. If you don’t wish to modify your CSV file to fit the pre-existing mapping, all you have to do is specify the correct column index in this mapping configuration. Since we’re ultimately going to be using the client.add, client.contact_add, and uber.admin_client_relationship_add methods, you may want to take a moment to review the documentation for those calls now.
Next, we initialize the client, and retrieve the contents of a file called customer_list.csv. You can change this filename to refer to another file if you wish; please ensure the file is readable and has its permissions set correctly. Now we loop over the rows in the CSV file, attempting to create a client for each one using the given mapping. In sequence, we add the client, then their contacts, and finally, their salesperson as a relationship. This is repeated for each row in the CSV file. Provided that the file is well-formatted and the mapping is defined correctly, you should end up with a list of clients in your Ubersmith instance. Using scripts like this for batch operations is a powerful way to do one-time migrations, ongoing maintenance, or any kind of synchronization with another system. Try some of the other examples on your own to see how they work.
The next step is to start modifying these files to see how you can modify their behavior. After you become accustomed to this, you’ll be ready to start extending Ubersmith’s behavior via the API in any way you choose. Note that you aren’t required to use our API client. You can also simply POST data to the API endpoint by using a web extension like Postman, or write your own client that leverages cURL. For simple calls, you can also use the API directly in the browser via URL parameters, as described in our API documentation. However, the examples in our repository all rely on our API client.
As always, if you have any questions that are not clearly answered by our API documentation, you can contact us for assistance.
