Making Your First API Call

A step-by-step walkthrough of making your first authenticated request to the SpherePay API.

This guide walks you through making your first API call — listing your customers. It assumes you have already obtained an API key from the Dashboard. If you have not, see Authentication first.

Base URL

All API requests are made to: https://api.spherepay.co/

Step 1 — Make a test request

The simplest call you can make is listing your customers. This confirms your API key is valid and your connection is working:

curl https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response will return an array of customer objects (empty if you have none yet):

{
  "customers": []
}

Step 2 — Create your first customer

Once your connection is confirmed, create an individual customer:

curl -X POST https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a4e1b2c3-d5f6-7890-abcd-ef1234567890" \
  -d '{
    "type": "individual",
    "email": "jane.doe@example.com",
    "phone": "+14155551234"
  }'

A successful response returns the newly created customer object with a system-generated id:

{
  "id": "customer_abc123",
  "type": "individual",
  "email": "jane.doe@example.com",
  "createdAt": "2026-02-25T10:00:00.000Z"
}

A newly created customer must complete identity verification before any transfer can be initiated. See Individual KYC Flow for the next steps.

Step 3 — Handle errors

If your request fails, SpherePay returns a structured error object with a consistent format across all endpoints. See the API Reference for specific error codes returned by each endpoint.

Next steps

Now that you have made your first API call, the next step is to onboard your customer through the KYC or KYB process before initiating transfers.