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:
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.
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:
https://buildname.simpro.co/api/oauth/request_token.php
https://buildname.simpro.co/oauth/authorize.php
https://buildname.simpro.co/api/oauth/access_token.php
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.
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.
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
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/0Request:
> 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"}
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
> 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-urlencodedResponse:
< 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
https://sandbox.simpro.co/oauth/authorize.php?oauth_token=AAEAAAAAcgAAAADT8DZPnB1tJh0j5EAmWDWEhcgzolFWI3qaVDOeLCscfQ
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-urlencodedResponse:
< 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
> 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"}
> 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"}