Skip to main content

Adding Customers

The Customers API enables you to directly pass KYC information to Sphere. This endpoint allows you to control the UI and handle all interactions with customers, whether they are individuals or businesses.

Individual Customer Creation​

POST v1/customers
curl https://api.sphere.net/v1/customer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "firstName": "John",
    "lastName": "Doe",
    "email": "johndoe123@gmail.com",
    "phoneNumber": "+12345678900",
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "postalCode": "94107",
      "state": "CA",
      "country": "USA"
    },
    "dob": {
      "month": 3,
      "day": 23,
      "year": 1990
    }
  }'

Business Customer Creation​

POST v1/customers
curl https://api.sphere.net/v1/customer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "business",
  "name": "Example Inc.",
  "description": "Leading provider of everything",
  "businessType": "llc",
  "email": "team@example.com",
  "website": "https://example.com",
  "address": {
    "line1": "123 Business Ave",
    "line2": "Suite 100",
    "city": "Chicago",
    "state": "IL",
    "postalCode": "60601",
    "country": "USA"
  }
}'

KYC Status​

Upon customer creation, Sphere will review all KYC information and return a status field indicating the verification status. Possible statuses include:

  • incomplete - Initial state
  • underReview - Manual review in progress
  • approved - Verification successful
  • rejected - Verification failed

The average decision time for individual KYC is typically less than one minute. Business KYB reviews are usually completed within one business day.

Sample Response​

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "customer": {
      "id": "customer_8444b807ac58487d9ed2001e830c9e69",
      "type": "individual",
      "firstName": "John",
      "lastName": "Doe",
      "email": "johndoe123@gmail.com",
      "phoneNumber": "+12345678900",
      "kyc": "incomplete",
      "tos": "incomplete",
      "address": {
        "line1": "123 Main St",
        "line2": null,
        "city": "San Francisco",
        "postalCode": "94107",
        "state": "CA",
        "country": "USA"
      },
      "created": "2024-08-22T16:13:01.227Z",
      "updated": "2024-08-22T16:13:01.227Z"
    }
  },
  "ts": "2024-08-22T16:13:02.026Z",
  "request": "request_29562171ced84c5ea09df36ef22101e8"
}