Back to top  

Introduction

An API or application programming interface is a set of routines, protocols, and tools for building software applications. In simpler terms; it.s a gateway into an application to allow 3rd party developers to retrieve and insert specified data into that application.

simPRO provides an API so that programmers can write applications consistent with the operating environment. Although APIs are designed for programmers, they are ultimately good for users because external applications can be created to move common data between simPRO and different applications (see below).

simPRO maintains an open platform that supports development of applications that will integrate with simPRO and third party applications. We assist in managing workflows and improving efficiencies for thousands of trade service businesses. We want to empower our ecosystem partners to build valuable businesses around the information flowing through simPRO. At the same time, we aim to strike a balance between encouraging interesting development and protecting both simPRO's and our users' rights.

So, we've come up with a set of Developer Rules that describes the policies and philosophy around what type of innovation is permitted with the content and information shared in simPRO.

The Rules will evolve along with our ecosystem as developers continue to innovate and find new, creative ways to use the simPRO API, so please check back periodically to see the current version. Don't do anything prohibited by the Rules and talk to us if you think we should make a change or give you an exception.

With the API you can now create integrations that connect simPRO to:

  • Mailing Systems
  • Accounting Systems
  • CRMs
  • eCommerce
  • Business Websites
  • Smartphone and Tablet Apps
  • Document Management Systems
  • and much more

Technologies / References

The simPRO API can be communicated with via JSON-RPC, XML-RPC, and has tentative[1]SOAP support.

Authentication is handled via OAuth 1.0. Basic Access Authentication is also available, but is deprecated and will be removed in a future version.

For security purposes, all communication with the API must take place over HTTPS.

1 SOAP Support hasn't been tested fully on all available platforms, also the WSDL provided doesn't define "static" data types for each response, and just provides a response envelope.

Access Points

The simPRO API has one main access point: https://buildname.simpro.co/api/?format=(soap|json|xml)

There are additional access points for retrieving / sending attachments as binary data: https://buildname.simpro.co/api/addAttachments.php, and https://buildname.simpro.co/api/getAttachment.php

And additional access points for applications using 'User Token Access' / '3 Legged' Open Authentication:

Request Token
https://buildname.simpro.co/api/oauth/request_token.php
Authorization
https://buildname.simpro.co/oauth/authorize.php
Access Token
https://buildname.simpro.co/api/oauth/access_token.php

Documentation

Procedures are separated into packages, and then into handlers. Packages denote a specific area of simPRO, eg Materials, while handlers denote a specific entity, eg Catalogue Items (CatalogueItemHandler).

Each handler has a set of methods exposed with a "procedure name" by which they can be called.

Obtaining Open Authentication Consumer Credentials

The method outlined here is for authenticating an application with a single simPRO Enterprise. If you'd like to offer integration with all simPRO Enterprise clients, please contact us.

To authenticate via OAuth, consumer credentials must be established. Consumer credentials can be managed by an authorised user, go to System > Setup, and then select API > Applications (on the left hand side). Finally, select 'Add Application', and complete the form. After creating an application, a key file containing the necessary credentials will be available.

Important Notes:

In the 'Authentication' section, choose a key that the application will use to identify itself. This must be unique, and must only contain lowercase letters and numbers, and the dash (-) character.

There are two types of access that an application can have, "direct access" or "user token access".

Direct Access applications can use their key to access all data available in simPRO via the API. This access is unfettered and is not associated with any employee credentials. This type of access is useful for integrating single point features with simPRO. For example, creating prospects in simPRO from a website, or accessing the simPRO catalogue directly to display on a website.

User Token Access applications must use the "3 Legged" Open Authentication process. To access the system, tokens must be granted access by users of the system, and actions taken by the application will be on their behalf.

Please note, the Company and Application URI will be shown to the users of the system before authorizing the application (See Screenshot)

Also, we strongly advise that the host/ subnet mask is used to restrict the use of oauth credentials. For example, restricting access to a single IP Address: 192.168.0.4, or to any computer on the local network: 192.168.0.0/24

Performing a Request

So now it's time to put it all together! Here's two example requests for listing the available companies in a build:

Direct Access

This request was generated using the following details: 
OAuth Details:
Consumer Key: sandbox-simpro
Consumer Secret: kQHjbVkKzPv0Y6-Oscwi2ORxBAev7PP-LjtTsH9Qv14K6TXqxPHXFOLaQoDmAjH0Kt48KRpeIFpcKcdBJA5z7Q
Signature Method: HMAC-SHA1
Access Type: 2-legged
Host/ Subnet: 0.0.0.0/0
Request: 
> POST /api/ HTTP/1.1
Host: sandbox.simpro.co
Authorization: OAuth,oauth_version="1.0",oauth_nonce="1d0c9d11a944b2439cf867f32d59d21b",oauth_timestamp="1355952869",oauth_consumer_key="sandbox-simpro",oauth_signature_method="HMAC-SHA1",oauth_signature="RLeoncaVjV%2FFl%2BMj0lPi%2BRaRQi4%3D"
Content-Type: application/json
Accept: application/json
Content-Length: 45

{"id":0,"method":"CompanySearch","params":[]}
Response: 
< HTTP/1.1 200 OK
< X-Powered-By: PHP/5.3.13
< Content-type: application/json
< Transfer-Encoding: chunked
< Date: Wed, 19 Dec 2012 21:35:36 GMT
< Server: lighttpd/1.4.28
< 
{"result":[{"CompanyID":0,"CompanyName":"Template Company","MailAddress":"\n","HomeAddress":"\n","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","BankAccountNo":"","BankAccountName":""},{"CompanyID":2,"CompanyName":"Company No. 1","MailAddress":"\n","HomeAddress":"\n","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","BankAccountNo":"","BankAccountName":""},{"CompanyID":3,"CompanyName":"Company No. 2","MailAddress":"\n","HomeAddress":"\n","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","BankAccountNo":"","BankAccountName":""},{"CompanyID":4,"CompanyName":"SimFIRE","MailAddress":"\n","HomeAddress":"123 Sim Street\nEight MiIle Plains, QLD 4113","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","BankAccountNo":"","BankAccountName":""},{"CompanyID":5,"CompanyName":"Integration Test - Don't Change","MailAddress":"\n","HomeAddress":"\n","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","
BankAccountNo":"","BankAccountName":""}],"error":null,"id":"0"}

User Token Acces

  1. First, we must obtain a consumer-key from the sandbox site: 
    OAuth Details:
Consumer Key: sandbox-simpro-token-access
Consumer Secret: hZh2HOrufxA_wJd5FQXIZDRclL5ADIShOrd5aSQLaZfkFrhiTCen4l13d3TFaU0m8gUcY8yJp-a1RpXBfFwb9Q
Signature Method: HMAC-SHA1
Access Type: 3-legged
Host/ Subnet: 0.0.0.0/0
  2. First, we must obtain a request token. Note, we'll be sending the special 'oob' value for the callback.
    Request: 
    > GET /api/oauth/request_token.php HTTP/1.1
Host: sandbox.simpro.co
Authorization: OAuth,oauth_version="1.0",oauth_nonce="b40cf36bd69e10ebbe289b82088a1089",oauth_timestamp="1355953958",oauth_consumer_key="sandbox-simpro-token-access",oauth_callback="oob",oauth_signature_method="HMAC-SHA1",oauth_signature="J6iPSL4O3bSoY9AByEIbtCbfkNI%3D"
Accept: application/x-www-form-urlencoded
    Response: 
    < HTTP/1.1 200 OK
< X-Powered-By: PHP/5.3.13
< Content-Length: 206
< Content-Type: application/x-www-form-urlencoded
< Date: Wed, 19 Dec 2012 21:53:46 GMT
< Server: lighttpd/1.4.28
< 
oauth_callback_confirmed=true&oauth_token=AAEAAAAAcgAAAADT8DZPnB1tJh0j5EAmWDWEhcgzolFWI3qaVDOeLCscfQ&oauth_token_secret=v-jx2BYNRpZPFeYZ2mUAW0Oombg-C4LWEh8ugEJeqJhPxMCl3hZxMIsWBP1bFztPqBu8bKvY_vyHFmlDUK1kfw
  3. Next, we must direct the user to authorize the token provided, by sending them to the following url: 
    https://sandbox.simpro.co/oauth/authorize.php?oauth_token=AAEAAAAAcgAAAADT8DZPnB1tJh0j5EAmWDWEhcgzolFWI3qaVDOeLCscfQ

  4. Once the user has authorised the application, and we've obtained the 'oauth verifier', we can then obtain the access token.

    Request: 
    > GET /api/oauth/access_token.php HTTP/1.1
Host: sandbox.simpro.co
Authorization: OAuth,oauth_version="1.0",oauth_nonce="b51686f4d9ebe08e268fa5100c4dff8b",oauth_timestamp="1355954449",oauth_consumer_key="sandbox-simpro-token-access",oauth_token="AAEAAAAAcgAAAADT8DZPnB1tJh0j5EAmWDWEhcgzolFWI3qaVDOeLCscfQ",oauth_verifier="UfsePZUT47BMCZQ6ixCtPw",oauth_signature_method="HMAC-SHA1",oauth_signature="GscXWNOKj0MRKJOc6AMwxlxY8A8%3D"
Accept: application/x-www-form-urlencoded
    Response: 
    < HTTP/1.1 200 OK
< X-Powered-By: PHP/5.3.13
< Content-Length: 176
< Content-Type: application/x-www-form-urlencoded
< Date: Wed, 19 Dec 2012 22:01:56 GMT
< Server: lighttpd/1.4.28
< 
oauth_token=AAEAAAAAYQAAAAB-5uszL6_plZCTc5qvLgTsuoARi2d-9wm1v9gyxOiZ1w&oauth_token_secret=3HdEuhFLdTkIuiWGnDrrJQueqTwumnFSrHtqp-7c0ecZucjidB56Ada0jwCe-uLX5rG41OICroz88QDfDEAiRA
  5. Now we have an access token, we can use this similarly to "direct access" to make requests to the API. For example:
    Request: 
    > POST /api/index.php HTTP/1.1
Host: sandbox.simpro.co
Authorization: OAuth,oauth_version="1.0",oauth_nonce="6cd89d8815d90c222d1809837f5babae",oauth_timestamp="1355954774",oauth_consumer_key="sandbox-simpro-token-access",oauth_token="AAEAAAAAYQAAAAB-5uszL6_plZCTc5qvLgTsuoARi2d-9wm1v9gyxOiZ1w",oauth_signature_method="HMAC-SHA1",oauth_signature="N2oOLLM%2BsF%2FkPj%2BBd1vgJ%2BJ6ifM%3D"
Content-Type: application/json
Accept: application/json
Content-Length: 45

{"id":0,"method":"CompanySearch","params":[]}
    Response: 
    < HTTP/1.1 200 OK
< X-Powered-By: PHP/5.3.13
< Content-type: application/json
< Transfer-Encoding: chunked
< Date: Wed, 19 Dec 2012 22:07:21 GMT
< Server: lighttpd/1.4.28
< 

{"result":[{"CompanyID":0,"CompanyName":"Template Company","MailAddress":"\n","HomeAddress":"\n","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","BankAccountNo":"","BankAccountName":""},{"CompanyID":2,"CompanyName":"Company No. 1","MailAddress":"\n","HomeAddress":"\n","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","BankAccountNo":"","BankAccountName":""},{"CompanyID":3,"CompanyName":"Company No. 2","MailAddress":"\n","HomeAddress":"\n","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","BankAccountNo":"","BankAccountName":""},{"CompanyID":4,"CompanyName":"SimFIRE","MailAddress":"\n","HomeAddress":"123 Sim Street\nEight MiIle Plains, QLD 4113","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","BankAccountNo":"","BankAccountName":""},{"CompanyID":5,"CompanyName":"Integration Test - Don't Change","MailAddress":"\n","HomeAddress":"\n","Phone1":"","Fax":"","Email":"","Website":"","ABN":"","Bank":"","BSB":"","
BankAccountNo":"","BankAccountName":""}],"error":null,"id":"0"}

File Uploads

  1. First, we must obtain a AttachmentKey from the respective handler you are uploading the attachment for, such as JobRetrieveAttachmentKey. Once this is done you can peform a POST request as below:
    Request: 
    > POST /api/addAttachment.php HTTP/1.1
Host: sandbox.simpro.co
< Content-Length:31758
< Content-Type:multipart/form-data; boundary=----WebKitFormBoundaryNu5DPaWnzMurAGNQ
------WebKitFormBoundaryNu5DPaWnzMurAGNQ
Content-Disposition: form-data; name="File"; filename="test.txt"
Content-Type: application/octet-stream


------WebKitFormBoundaryNu5DPaWnzMurAGNQ
Content-Disposition: form-data; name="AttachmentKey"

Mzc1NzM0ZmdoZF9kc2hlcmh3LmFkc2c=
    Response: 
    < HTTP/1.1 200 OK
< X-Powered-By: PHP/5.3.13
< Content-type: application/json
< Transfer-Encoding: chunked
< Date: Wed, 19 Dec 2012 22:07:21 GMT
< Server: lighttpd/1.4.28
< 

{"Success":"File Uploaded"}