HomeGuidesAPI Reference

Quick Start

Suggest Edits

Everything you need to get started building apps with the Merit API.

1. CHECKLIST

  • Account Setup: First things first, you'll need a Merit organization account, sign up here

    • Request an App ID and App Secret: These will allow you to authenticate your app with Merit

    • App Setup: App developers receive and implement their Merit App ID and App Secret

    • Read Use Cases: These will give you the quickest understanding of how to create a basic Merit app

    • Review API Reference: This is the detailed guide covering the entire Merit API

2. APP PERMISSIONS

  • Org level permissions: App developers will create a Web Flow for Org admins that will allow Org Admins to authenticate against Merit and grant the app a set of permissions. These permissions will allow the app to act on behalf of the Org

    • Member level permissions: App developers will create a Web Flow for Members that will allow Members to authenticate against Merit and grant this app a set of permissions. These permissions will allow the app to retrieve information about the Member from Merit

👍

The world is your oyster

Given these permissions, apps can make a series of REST API calls to realize anything you can imagine.

What can Merit apps do?

  • Send and Revoke merits: Merit apps can act on behalf of an organization to both send and revoke merits, this can be used to create apps that automatically award individuals merits in recognition of things they have achieved in the real world. This functionality can even be used to fully automate the issuance of merits for an organization based on custom criteria.

  • Create and Manage merit templates: Merit apps can perform almost all the functionality of a merit admin, allowing for apps that are able to perform template management activities, this can be used to automate complex workflows and reduce the need for manual management within an organization

  • Verify merits and ‘check-in’ individuals: Merit apps are able to log in individuals and check the status of their merits, this is done via allowing the app to send an ‘Access Merit’ to request access to an individual's merit data

Creating an App

Creating a new app is simple, just click ‘Start Building’ and give us some basic information and
You’ll receive an App ID and App Secret that together will form your the API key for your app.

❗️

KEEP YOUR APP SECRET... SECRET!

You should always store your App Secret safe, securely and secretly, never in a client app or your front end code, only on your own servers protected like you would a password.

📘

LET US KNOW IF ANYONE GETS YOUR SECRET OR YOUR LOSE IT

If your App Secret ever becomes public please reach out to [email protected] for help deactivating and replacing it.

👍

REQUIRED INFORMATION

To request an App Key and Secret you'll have to have the following information to hand. Make sure to prepare it all in advance of filling out the form:

Organization id (in Merit)
Your organization ID can be found by logging in to your Merit admin portal and just copy / pasting the whole URL of the any page in the portal as the answer for this question in the form.

Admin email (in Merit)
The email address associated with your organization account on Merit

App title
What is the app called?

App description
Describe your app in a way that fully explains the features, benefits, use cases and overall implementation details

App logo
This could be different from your organization profile logo and must be square

App url (where will the info about this app be located)
The landing page or website for you app

App terms of service url (placeholder is fine for now)
All apps require a terms of service document

App privacy policy url (placeholder is fine for now)
All apps require a privacy policy

App desired permission types from orgs and members
If you require special permissions, list them here

App success url and failure urls
These are used for callbacks when an auth flow succeeds or fails. You can use them to show appropriate messaging and next steps.

The Form is Located At: https://www.merits.com/request-merit-api-key

Managing an App

It is not currently possible to edit your app name or description, however should you need to you can revoke your App ID and App secret and generate a new one whenever you need to change anything reach out to [email protected]

Building an App

There are several start points depending on what you need to achieve, we recommend:

Distributing Your App

You are responsible for hosting your app in the place of your choosing.
Merit organizations can install your app by linking it with their organization's Merit account.
Linking with Orgs

When your app is complete we want to hear about it, let us know by emailing [email protected]

Updated almost 5 years ago