Quickstart Guide

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

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.melon.ng/api/v1/customers" \
  -H "Authorization: Bearer mk_test_123456789" \
  -H "Content-Type: application/json"

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, BVN/NIN, physical addresses) to the POST /api/v1/customers endpoint.
2. Verification Process: Melon dispatches field agents to the provided physical addresses to perform verification checks.
3. Listen for Updates: We highly recommend configuring Webhooks to receive real-time notifications (e.g., verification.completed, verification.rejected). Alternatively, you can poll for updates using the /api/v1/verification/:customerId/status endpoint.
4. Retrieve Report: Once verification is completed, you can fetch the final details and even download a formatted PDF report via the API.

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