Set up your environment

We will be using Postman for the next few steps. If you have not yet downloaded the free version of Postman, click here to get started.

NOTE: Use this tool only for testing and prototyping your API requests.

Import the Kindful OAuth collection into Postman

Each Kindful Non-OAuth collection was created to simplify the process of knowing what calls you can make to the Kindful API and how to set up your environment. It includes sample endpoints that you will have access to so that you can test them.

  • Download and install the Postman app
  • Click the "Run in Postman" button for the collection you'd like to test from the options below.
  • Select your version of postman on the dialog screen
  • Your Postman UI should be updated with the collection. You should see all the requests you can make in the API.
  • Configure the OAuth2 by defining the variables used in endpoints. An environment template was downloaded with the collection and can be updated via Edit in the collection settings.
Partner API Postman Collections
Playground Collection of individual resource endpoints
Production Collection of individual resource endpoints

Now, that you have all the calls imported, let’s set up authentication so that you can send your first request.

Add OAuth2 to Postman

It is required that you setup postman using OAuth2 because your integration must authenticate using this method, and testing your endpoints using OAuth2 will guide you through the partner dashboard on how to set up OAuth2. It is also the quicker method to get started.

In Partner Dashboard

  • From the Partner Dashboard, navigate to “Testing”
  • Ensure that there is a Test Account Available in the Partner Dashboard. If there is not one, create it by clicking “New Test Account” and follow the steps
  • Navigate to Applications
  • Create a New Application
  • Select “Manage” by the application you just created
  • Select the “PLAYGROUND” tab
  • Copy/Paste https://www.getpostman.com/oauth2/callback into the space provided for the Redirect URI(s)
  • Click “Update Application”
  • You will now have a Key and a Secret

Head over to Postman...

In Postman

  • Open Postman
  • Hover over the collection folder that you imported earlier
  • Select the “...”
  • Choose “Edit” from the options
  • Click on the Authorization Tab
  • Click “Get New Access Token”
  • Assign a Token Name
  • Callback URL: https://www.getpostman.com/oauth2/callback
  • Auth URL: https://app-playground.kindful.com/admin/oauth2/authorize
  • Access Token URL: https://app-playground.kindful.com/admin/oauth2/token
  • Copy/Paste Key from Partner Dashboard into Client ID
  • Copy/Paste Secret from Partner Dashboard into Client Secret

  • Based on your integration requirements, set the Scope to any/all of the following:

    • basic -- Access Kindful Account details. Allows all GET requests and setting integration status.
    • data_add -- Create & update records in Kindful.
    • data_query -- Access Contact and Transaction records in Kindful.
  • Select “Request Token”
  • It is possible that you will not be able to see the whole login form because Postman may cut it off, so TAB until you see "Sign In with Partner Dashboard Credentials" and click the link
  • Log in using your Partner Dashboard Creds
  • Select the Test Account you want to use from the select menu and click “Continue”
  • Authorize the application
  • In Postman, select “Use Token”
  • Select “Update”

You're all set!

The instructions above can be followed to create a Production environment in Postman as well. The URLs are as follows:

  • Auth URL: https://app.kindful.com/admin/oauth2/authorize
  • Access Token URL: https://app.kindful.com/admin/oauth2/token

Send the first request to your Integration

Now, here is where the fun begins! With your Integration environment set up, you should be able to send a test to your Playground!

  1. Under “Collections” in the “Kindful API OAuth2” folder, click “POST contact”.
  2. Click the blue “Send” Button next to the endpoint URL.

Your response should look like this:

COPY 
{
    "id": "4d626eaf-5441-4d34-8a4f-5bc1d6baed83",
    "status": "pending"
}

HOUSTON WE HAVE LIFT OFF! 👏👏👏

HTTP Token: Access Denied

POSSIBLE ERROR: If the response is “HTTP Token: Access Denied,” you have used the incorrect Application Token. Be sure that you used the token that was generated in the Playground and not in Production.

THE FIX: If you have used the wrong Application Token, click the cog in the top right corner to open the “Manage Environments” dialog box. Select “Sandbox” and update your Application Token’s “initial value” and “current value”. Select “Update” and try the call again.

Check out your import in the Playground

Let’s head back to the Partner Dashboard.

  • Select “Manage” under Options next to your application
  • Click the Playground Tab and select Requests
  • The Job ID that was returned in Postman should be in the list
  • Once the status is “Complete”, Select “Testing” from the main navigation
  • Under Options for your organization, select “Launch”
  • In the Kindful Dashboard, you will see the number one (1) under “Total Contacts”
  • That is your import! Way to go!