HomeGuidesAPI Reference

Quick Start

Suggest Edits

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

CHECKLIST

  • Organization 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 (see "Getting an App" below)

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

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

Sandbox vs Production

Sandbox Environment Limitations
All integrations must first be built, tested, and reviewed within the sandbox environment before they can be deployed to Merit's production environment.

It is important to note that the sandbox environment prevents outgoing email by default. This is intended to allow for tests to be performed without real-world users being involved, although ideally any data being submitted into the sandbox environment has been anonymized, having been scrubbed of any PII. As these emails are necessary for onboarding, sending merits, etc., it is necessary to ensure that either your development team's emails, or your whole company's domain has been added to the allowed list for sending emails before any work can begin.

Sandbox vs Production API URL
Sandbox API URL: https://sandbox-api.merits.com
Production API URL: https://api.merits.com

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

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

Getting an App

If you'd like to start building on Merit, please reach out to [email protected]
From there, we will help you get up and running in our sandbox environment.

❗️

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 ID and App Secret, you will need to provide the below information to [email protected]:

Organization id (in Merit)
Your organization ID can be found by logging in to your Merit admin portal (https://app.merits.com) and copying the URL of the any page in the portal. Your Org ID is the first ID that appears in the URL, immediately following /admin/ or /org/.

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 should represent the app, and could simply be your organization's logo. Minimum size of 200*200px recommended.

App url (where will the info about this app be located)
The landing page or website for you app. If you are using the Login With Merit or Link With Merit authentication/authorization flows, this will be the base URL used for OAuth like redirects upon successful or failed attempts to login. Must be an HTTPS URL.

App terms of service url (placeholder is fine for now)
All apps require a terms of service document. Must be an HTTPS URL.

App privacy policy url (placeholder is fine for now)
All apps require a privacy policy. Must be an HTTPS URL.

Managing an App

Should you need to update any details about your app, including the title, description, app URL, etc. 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 11 months ago