What are API Partners?

With the standard API in QuickFile you can easily define applications at the account level and we will give you a few authentication credentials you can use to make calls to the API. This is great when you just want to create some bespoke tool for your own use, but becomes problematic when you want to develop something for the wider community.

As an API Partner we provide you with a framework you can use so you can tell other users about your API product e.g.

• What is it called?
• What does it do?
• What permissions will it require?
• What is the cost to the end-user?
• Is there a website with more information?

This information is visible to all QuickFile users and will allow them to grant access to the application from the ‘Services’ area in their QuickFile account.

Once access has been granted the end-user will receive a token they can enter into your application with their account number. This combination can then be used to access their regular API credentials and interface with all granted endpoints defined in the product.

How do I become an API Partner?

Becoming an API Partner takes just a few clicks. First head over to the “My Apps” section of your account, here you will see a link “Become an API Partner”. Click this link and we’ll set you up with a new Partner Dashboard where you can start defining your products.

Creating your first product

Now you are an API Partner you will want to tell other QuickFile users about your product. On your API Partner Dashboard click the green button ‘Create’. This will open a dialogue box where you can enter some information about the product you have built.

Once your product details have been saved it will convert to ‘STAGING’ status. While your product is in staging you will be able to test your integration on your account, you can also add up to 5 additional test accounts. You can add a test account to your list by clicking on the corresponding edit link for the product in question.

Your app details

Each app will be tied to your own QuickFile account. There are 2 main things to be aware of:

• Your Secret Key (which is unique to your QuickFile account)
• Your app Product Key (which is unique to your app)

The secret key will be used as part of your app authentication process (see below), whereas the product key is used to determine the app the user has authorised.

How should the product key be used?

You could offer a few different apps but all accessible from one location; for example, a file uploader, and an invoice creator. QuickFile will send the product key back to you as part of the authentication so you know which of the apps the user has authorised. This can then be checked against the value provided in the API Partners dashboard.

This part however is optional, and wouldn’t necessarily be required if you only offer one app on the marketplace.

Testing your app

Testing your app is an important step before going live, and QuickFile allows you to grant access to a select group of users, so you could even allow other users to test your app too.

To invite a test user, you will need their QuickFile Account Number. By providing this to QuickFile, we’ll send them an invite which will add the app to their account for you. Only users on the tester list will see your app until it’s deployed and approved.

To add a tester, start by editing your app details on the partner dashboard. This opens up your app details, including a link to add testing accounts. You can add up to five accounts here.

When you add an account, we’ll send them an email with the option to accept the invite to test the app. Once they accept this, it will appear in the App Marketplace for them to add it, just like you would any other app.

The email we send your user will be similar to this:

Deploying your application to the Marketplace

QuickFile includes a Marketplace area where your custom products will be accessible to the wider QuickFile community. Before a product can become generally available on the Marketplace you will first need to deploy that application, you should perform this task once you have thoroughly tested it’s functionality while in staging mode.

To deploy your application click on the corresponding ‘view’ link and click the green ‘Deploy Product’ button:

In most cases a member of the QuickFile team will review your application within 24 hours. Once reviewed we will notify you by email and publish your product to the QuickFile Marketplace area.

Retrieving end-user API credentials

As an API partner you will need to make calls to a dedicated endpoint that will enable you to retrieve your end-user’s regular API credentials, this will then permit you to make all necessary API calls defined in your product specification.

The Partner endpoint for retrieving API credentials is as follows:

https://api.quickfile.co.uk/partners/authenticate

Simply make a HTTP post request passing two variables in the body:

token: xxxx
md5: yyyy

You will also need to set your content type to application/x-www-form-urlencoded.

The token is the value supplied by the end user and generated on the marketplace when an end-user activates a new product.

The md5 value is a hash that is used as a signature for the call. This MD5 hash should be created by concatenating the end-users account number with your secret key (Visible on your partner dashboard)

eg. 6131400001:1hQT9NNYkKH7q53elG3RvwnT

Hashes to:

45d59c6fa424dfd8f87a59be9045336f

There’s a useful tool here for generating your own MD5 hash.

If the request is successful the partner API will return a HTTP 200 status code with some JSON that will provide you with an api_key and an application_id, these credentials can then be used by all other methods within the QuickFile API to authorise your calls.

{
  "api_key": "1DF67A1D-06CA-44FF-0",
  "application_id": "f22eadae-d6a3-4fc8-811b-6cbd1v633124",
  "product_key": "F89B623D-8CH8-41DA-86E7-1654258919EA"
}

If the credentials supplied could not be verified you would typically receive a HTTP 400 response.

Private Apps

You may wish to develop an app that you want to make available for a select group of users. An example of this would be where you have a QuickFile account for different franchisees of an organisations, and wish for them to use the app on each of their accounts.

When you deploy the app, you have the option to set it as a private app. This means that each account has to be authorised within the app settings before it can be activated on their end. The authentication process is exactly the same once it’s been authorised.

To mark is as a private app, click on ‘Edit’ next to the app you wish to update, and tick the ‘Private Application’ box.

This will reveal an option to edit the private group at the top of the settings

Remember to save your settings so the app will remain private.