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
- Open the Postman desktop client. In the upper left click
Import
- 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
- Verify the below details and click
Import
- 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
- In the postman desktop app, click on
Environments
on the panel on the left side. Click on the+
in the upper left corner.
- 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
.
- This is what our env looks like filled out - be sure to fill in
public-dealer-id
andprivate-api-key
with your own credentials
- 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
Environment | Base URL | Playground Access |
---|---|---|
Sandbox | https://application-edge-service.sandbox.koalafi.com | Yes |
Production | https://application-edge-service.koalafi.com | No |
Updated almost 2 years ago