Quickstart Guide

This guide will walk you through the end-to-end process of integrating the Melon API into your application.

[!TIP] Prefer to learn by doing? Check out our Postman Workspace to instantly sandbox the API endpoints in your own environment.

1. Choose an API Plan

Select the API plan that fits your usage needs:

• Developer (Free): Sandbox-only access for exploration and testing. (100 requests/day, 50 test records)
• Growth ($500/mo + $2/verification): Production access for small-to-mid integrations. (10,000 requests/day)
• Enterprise ($2,500/mo + $1.50/verification): High-volume partners with unlimited records, dedicated support, and white-labeling options.

You can upgrade your plan at any time from your Dashboard.

2. Obtain API Keys

Upon registering and setting up your workspace, you can generate API keys from the Developers section of your dashboard.

Melon supports two distinct environments to ensure safe testing:

• Sandbox Environment: Keys begin with mk_test_. Use this to safely test your integration without affecting live records or incurring charges. Mock data is returned.
• Live Environment: Keys begin with mk_live_. Use this in your production systems for real verifications.

[!WARNING] Keep your mk_live_ API keys secret! Do not expose them in client-side code (e.g., frontend JavaScript, mobile apps). All API calls should be made from your secure backend servers.

3. Make Your First Request

To authenticate with the API, include your secret key in the Authorization header as a Bearer token.

curl -X GET "https://api.example.com/api/v1/customers" \
  -H "Authorization: Bearer mk_test_123456789" \
  -H "Content-Type: application/json"

fetch("https://api.example.com/api/v1/customers", {
  method: "GET",
  headers: {
    "Authorization": "Bearer mk_test_123456789",
    "Content-Type": "application/json"
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

import requests

url = "https://api.example.com/api/v1/customers"
headers = {
    "Authorization": "Bearer mk_test_123456789",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {
	url := "https://api.example.com/api/v1/customers"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Add("Authorization", "Bearer mk_test_123456789")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(string(body))
}

If successful, you will receive a standard API response envelope containing your requested data.

4. Understanding the Integration Workflow

The typical lifecycle for verifying a customer through our API looks like this:

1. Create Customer: Your application sends customer data (name, phone, email, physical addresses with agent instructions, and optional supporting documents) to the POST /api/v1/customers endpoint. You can also append documents at any time via POST /api/v1/customers/:id/documents.
2. Verification Process: Melon dispatches field agents to the provided physical addresses to perform verification checks, capture geo-tagged photo evidence, and interview residents.
3. Listen for Updates: We highly recommend configuring Webhooks to receive real-time notifications (e.g., verification.completed, verification.rejected). Webhook payloads include verified GPS coordinates, agent field notes, photo URLs, and rejection diagnostics. Alternatively, you can query /api/v1/verification/:customerId/status.
4. Retrieve Report: Once verification is completed, you can fetch the final details and download a formatted PDF report via GET /api/v1/customers/:id/report.

Ready to dive deeper? Check out the Authentication guide or jump straight into the API Reference.