Skip to main content
POST
/
customers
/
Create a customer
curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/customers/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "unique-customer-id-456",
  "email": "another.new.customer@example.com",
  "name": "Jane Roe",
  "metadata": {
    "source": "sdk_import",
    "priority": "low"
  },
  "billingAddress": {
    "country": "IN",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "postalCode": "560001",
    "city": "Bangalore",
    "state": "Karnataka"
  }
}
'
import requests

url = "https://sandboxapi.kelviq.com/api/v1/customers/"

payload = {
    "customerId": "unique-customer-id-456",
    "email": "another.new.customer@example.com",
    "name": "Jane Roe",
    "metadata": {
        "source": "sdk_import",
        "priority": "low"
    },
    "billingAddress": {
        "country": "IN",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "postalCode": "560001",
        "city": "Bangalore",
        "state": "Karnataka"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: 'unique-customer-id-456',
    email: 'another.new.customer@example.com',
    name: 'Jane Roe',
    metadata: {source: 'sdk_import', priority: 'low'},
    billingAddress: {
      country: 'IN',
      line1: '123 Main Street',
      line2: 'Apt 4B',
      postalCode: '560001',
      city: 'Bangalore',
      state: 'Karnataka'
    }
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/customers/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandboxapi.kelviq.com/api/v1/customers/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerId' => 'unique-customer-id-456',
    'email' => 'another.new.customer@example.com',
    'name' => 'Jane Roe',
    'metadata' => [
        'source' => 'sdk_import',
        'priority' => 'low'
    ],
    'billingAddress' => [
        'country' => 'IN',
        'line1' => '123 Main Street',
        'line2' => 'Apt 4B',
        'postalCode' => '560001',
        'city' => 'Bangalore',
        'state' => 'Karnataka'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

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

func main() {

	url := "https://sandboxapi.kelviq.com/api/v1/customers/"

	payload := strings.NewReader("{\n  \"customerId\": \"unique-customer-id-456\",\n  \"email\": \"another.new.customer@example.com\",\n  \"name\": \"Jane Roe\",\n  \"metadata\": {\n    \"source\": \"sdk_import\",\n    \"priority\": \"low\"\n  },\n  \"billingAddress\": {\n    \"country\": \"IN\",\n    \"line1\": \"123 Main Street\",\n    \"line2\": \"Apt 4B\",\n    \"postalCode\": \"560001\",\n    \"city\": \"Bangalore\",\n    \"state\": \"Karnataka\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://sandboxapi.kelviq.com/api/v1/customers/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"unique-customer-id-456\",\n  \"email\": \"another.new.customer@example.com\",\n  \"name\": \"Jane Roe\",\n  \"metadata\": {\n    \"source\": \"sdk_import\",\n    \"priority\": \"low\"\n  },\n  \"billingAddress\": {\n    \"country\": \"IN\",\n    \"line1\": \"123 Main Street\",\n    \"line2\": \"Apt 4B\",\n    \"postalCode\": \"560001\",\n    \"city\": \"Bangalore\",\n    \"state\": \"Karnataka\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/customers/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerId\": \"unique-customer-id-456\",\n  \"email\": \"another.new.customer@example.com\",\n  \"name\": \"Jane Roe\",\n  \"metadata\": {\n    \"source\": \"sdk_import\",\n    \"priority\": \"low\"\n  },\n  \"billingAddress\": {\n    \"country\": \"IN\",\n    \"line1\": \"123 Main Street\",\n    \"line2\": \"Apt 4B\",\n    \"postalCode\": \"560001\",\n    \"city\": \"Bangalore\",\n    \"state\": \"Karnataka\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "customerId": "unique-customer-id-123",
  "name": "John Doe",
  "email": "new.customer@example.com",
  "details": {},
  "metadata": {
    "source": "sdk_import",
    "priority": "high"
  },
  "billingAddress": {
    "country": "IN",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "postalCode": "560001",
    "city": "Bangalore",
    "state": "Karnataka"
  },
  "createdOn": "2025-06-04T06:03:30.195790Z",
  "modifiedOn": "2025-06-04T06:03:30.195831Z"
}
Click the base URL in the API playground and select the Sandbox host for test data or the Production host for live data. Use credentials from the same environment.

Authorizations

Authorization
string
header
required

The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer YOUR_API_KEY'

Body

application/json
customerId
string
required

A unique identifier for the customer that you define.

Example:

"unique-customer-id-456"

email
string<email> | null

The email address of the customer.

Example:

"another.new.customer@example.com"

name
string | null

The name of the customer.

Example:

"Jane Roe"

metadata
object | null

A dictionary of custom key-value pairs.

Example:
{ "source": "sdk_import", "priority": "low" }
billingAddress
object | null

The billing address of the customer.

Response

201 - application/json

Customer Created

id
string<uuid>
read-only

Server-generated unique UUID for the customer record.

Example:

"a1b2c3d4-e5f6-7890-1234-567890abcdef"

customerId
string

The client-provided customer identifier.

Example:

"unique-customer-id-123"

name
string | null

The customer's name.

Example:

"John Doe"

email
string<email> | null

The customer's email.

Example:

"new.customer@example.com"

details
object
read-only

Any server-added details about the customer (typically read-only).

Example:
{}
metadata
object | null

The metadata associated with the customer.

Example:
{
  "source": "sdk_import",
  "priority": "high"
}
billingAddress
object | null

The billing address of the customer.

createdOn
string

Customer created date and time

Example:

"2025-06-04T06:03:30.195790Z"

modifiedOn
string

Customer updated date and time

Example:

"2025-06-04T06:03:30.195790Z"