Using our API

Credentials

API Keys

Koalafi has both protected apis and unprotected apis. For unprotected apis we authorize your request based on a Public Dealer ID and for protected we use a Private API key that are passed up via a header in the request. Using these values will allow you to securely access our apis.

Obtaining your API Keys

During dealer onboarding you will be issued a public dealer id and a private api key. In order to call our unprotected apis you will need to provide this value in a public-dealer-id header for each request. For more information on onboarding, view Onboard with Koalafi

{  
  "public-dealer-id":"<public dealer id value>"  
}

For our protected APIs you will need to add a private-api-key header to the protected request.

{  
  "public-dealer-id":"<public dealer id value>",  
  "private-api-key":"<private api key value>"
}

Tracking Requests

To make troubleshooting requests easier, you can include an optional correlation-id header with a GUID value. We will add this correlation-id to our logs so that if you run into an issue while testing, we can pull the logs for that request. We recommend passing this header in both sandbox and production.

Sandbox Testing

Once you have your sandbox credentials you can start testing in sandbox. Our APIs are built using graphQL, if you are new to it we recommend this tutorial.

GraphQL Playground

Our sandbox GraphQL playground is the perfect place to build different queries and mutations. The playground has tabs that open our docs and the schema. As you build your queries, the playground will validate the schema which makes it a great tool to become more familiar with both GraphQL and our schema. The Koalafi playground is only available in our sandbox environment and for security reasons is not enabled in production.

To use the playground you will need to include the following headers on any queries/mutations

{
"public-dealer-id": <your-PDI-here>,
"private-api-key": <your-key-here>
}

📘

All of our most frequently used queries are included in a public Postman collection that is linked below.

Example Response

Below is a generic example response. Whenever you query our endpoints you will always get back two objects - the success object and the error object. In the example below, sampleField represents the success object and sampleMutationErrors represents the error object. Always check the length of the error object before moving forward with the successObject. If there are no errors returned, the length of the error object will be 0.

mutation {
  sampleMutation(
    input: {
      sampleFakeBoolean: true
    }
  ) {
    sampleField
    sampleMutationErrors {
      __typename // include this to get the error type back
      ... on ErrorA { // optional
        message
      }
      ... on ErrorB { // optional
        message
      }
    }
  }
}

In the above example, we would check the length of sampleMutationErrors. If length is 0, the mutation was a success, and we can use our sampleField. If length > 0, the __typename field can be used to see the type of error returned. Including the optional ... on ErrorA { message } fragment in our query, we can use that message to get more details on the error that occurred. A comprehensive view of possible errors is in the docs on our playground. We also have a guide called Handling Common Errors with our recommendations for how to handle the different errors that may occur.

Postman

🚧

Postman Updates Incoming

Postman has deprecated the ability to share a private collection via URL. The current postman collection has a few outdated mutations/queries. We are currently updating our collection and working on a new solution to ensure everything stays up to date. Until the update is complete, continue to use the current collection but cross reference with our Direct API docs and our schema on the playground. If you have any questions you can email our dev team at [email protected]

We will remove this box once the links below are up to date

Collection

If you are already familiar with GraphQL or would like some guidance on how to create and structure your queries you can use our postman collection. Our postman collection has example requests for all of our common queries/mutations. The endpoint and some headers are setup to be used with a postman environment but you will need to add your API credentials to the headers. The headers are configured to use a Postman Environment, please see the following section Environment for configuring your postman environment.

Koalafi_Integrations_Public Postman Collection

Import Our Collection

1. Open the Postman desktop client. In the upper left click Import

2. In the menu that opens up click Link and paste the URL for the Koalafi postman collection: https://www.getpostman.com/collections/1d2587bb2cc9a22ce1aa. Click continue

3. Verify the below details and click Import

4. The collection should not be imported and ready to use. Inside the collection, the requests are organized in the same structure as our Direct API docs.

Environment

We recommend using a Koalafi postman environment for testing. You can use the following JSON key/value pairs to set up your Koalafi-sandbox env.

{
	"name": "Koalafi-Sandbox",
	"values": [
		{
			"key": "base_url",
			"value": "https://application-edge-service.sandbox.koalafi.com",
			"enabled": true
		},
		{
			"key": "private-api-key",
			"value": "<your key> ",
			"enabled": true
		},
    {
			"key": "public-dealer-id",
			"value": "<your pdi>",
			"enabled": true
		},
		{
			"key": "rn-high-approval",
			"value": "011000028",
			"enabled": true
		},
		{
			"key": "rn-hard-decline",
			"value": "011001234",
			"enabled": true
		},
		{
			"key": "rn-soft-decline",
			"value": "011001276",
			"enabled": true
		},
		{
			"key": "base_",
			"value": "",
			"enabled": true
		},
		{
			"key": "rn-soft-decline-identity",
			"value": "011000536",
			"enabled": true
		}
	],
}

Creating your Postman Environment

1. In the postman desktop app, click on Environments on the panel on the left side. Click on the + in the upper left corner.

2. This will create a new empty environment for you. Change the name to something meaningful - we chose Koalafi-Sandbox-Public. Copy over the key-value pairs from the JSON above. Each key-value pair is it's own line in the environment. The type for each pair should be set to default.

3. This is what our env looks like filled out - be sure to fill in public-dealer-id and private-api-key with your own credentials

4. Your environment setup is complete and you should now see your new environment under the environments tab. You should now be able to use our collection

Connecting to our Environments