Create a client

curl --request POST \
  --url https://mgmt-api.voxfra.com/v1/clients \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "ABC Motors",
  "display_name": "ABC Motors - Downtown",
  "type": "automotive",
  "subscription_plan": "Pro",
  "status": "active",
  "contact_person": "Jane Smith",
  "contact_email": "[email protected]",
  "phone_number": "+15551234567"
}
'

import requests

url = "https://mgmt-api.voxfra.com/v1/clients"

payload = {
    "name": "ABC Motors",
    "display_name": "ABC Motors - Downtown",
    "type": "automotive",
    "subscription_plan": "Pro",
    "status": "active",
    "contact_person": "Jane Smith",
    "contact_email": "[email protected]",
    "phone_number": "+15551234567"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'ABC Motors',
    display_name: 'ABC Motors - Downtown',
    type: 'automotive',
    subscription_plan: 'Pro',
    status: 'active',
    contact_person: 'Jane Smith',
    contact_email: '[email protected]',
    phone_number: '+15551234567'
  })
};

fetch('https://mgmt-api.voxfra.com/v1/clients', 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://mgmt-api.voxfra.com/v1/clients",
  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([
    'name' => 'ABC Motors',
    'display_name' => 'ABC Motors - Downtown',
    'type' => 'automotive',
    'subscription_plan' => 'Pro',
    'status' => 'active',
    'contact_person' => 'Jane Smith',
    'contact_email' => '[email protected]',
    'phone_number' => '+15551234567'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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://mgmt-api.voxfra.com/v1/clients"

	payload := strings.NewReader("{\n  \"name\": \"ABC Motors\",\n  \"display_name\": \"ABC Motors - Downtown\",\n  \"type\": \"automotive\",\n  \"subscription_plan\": \"Pro\",\n  \"status\": \"active\",\n  \"contact_person\": \"Jane Smith\",\n  \"contact_email\": \"[email protected]\",\n  \"phone_number\": \"+15551234567\"\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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://mgmt-api.voxfra.com/v1/clients")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"ABC Motors\",\n  \"display_name\": \"ABC Motors - Downtown\",\n  \"type\": \"automotive\",\n  \"subscription_plan\": \"Pro\",\n  \"status\": \"active\",\n  \"contact_person\": \"Jane Smith\",\n  \"contact_email\": \"[email protected]\",\n  \"phone_number\": \"+15551234567\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://mgmt-api.voxfra.com/v1/clients")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"ABC Motors\",\n  \"display_name\": \"ABC Motors - Downtown\",\n  \"type\": \"automotive\",\n  \"subscription_plan\": \"Pro\",\n  \"status\": \"active\",\n  \"contact_person\": \"Jane Smith\",\n  \"contact_email\": \"[email protected]\",\n  \"phone_number\": \"+15551234567\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "ABC Motors Test Client",
    "display_name": "ABC Motors - Downtown",
    "type": "automotive",
    "subscription_plan": "pro",
    "contact_person": "<string>",
    "contact_email": "[email protected]",
    "phone_number": "<string>",
    "joined_at": "2023-11-07T05:31:56Z",
    "last_active_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": "Bad Request",
  "message": "name is required."
}

{
  "error": "Unauthorized"
}

{
  "error": "Conflict",
  "message": "A client with this name already exists in your organization."
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "Internal Server Error",
  "message": "Unexpected error"
}

Clients

Create Client

Provisions a new client within the authenticated organization.

Validation rules:

name, type, and subscription_plan are required. name is unique within your organization.
contact_email must be a valid email address. Phone numbers must be 7-15 digits with an optional leading +.
status defaults to active if omitted and must be one of active, inactive, trial, churned, pending.
A URL-safe slug is derived from name automatically; collisions are resolved with a numeric suffix.

Rate limit: this endpoint is capped at 10 requests per minute per API key in addition to the default per-key limit.

POST

clients

Create a client

curl --request POST \
  --url https://mgmt-api.voxfra.com/v1/clients \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "ABC Motors",
  "display_name": "ABC Motors - Downtown",
  "type": "automotive",
  "subscription_plan": "Pro",
  "status": "active",
  "contact_person": "Jane Smith",
  "contact_email": "[email protected]",
  "phone_number": "+15551234567"
}
'

import requests

url = "https://mgmt-api.voxfra.com/v1/clients"

payload = {
    "name": "ABC Motors",
    "display_name": "ABC Motors - Downtown",
    "type": "automotive",
    "subscription_plan": "Pro",
    "status": "active",
    "contact_person": "Jane Smith",
    "contact_email": "[email protected]",
    "phone_number": "+15551234567"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'ABC Motors',
    display_name: 'ABC Motors - Downtown',
    type: 'automotive',
    subscription_plan: 'Pro',
    status: 'active',
    contact_person: 'Jane Smith',
    contact_email: '[email protected]',
    phone_number: '+15551234567'
  })
};

fetch('https://mgmt-api.voxfra.com/v1/clients', 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://mgmt-api.voxfra.com/v1/clients",
  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([
    'name' => 'ABC Motors',
    'display_name' => 'ABC Motors - Downtown',
    'type' => 'automotive',
    'subscription_plan' => 'Pro',
    'status' => 'active',
    'contact_person' => 'Jane Smith',
    'contact_email' => '[email protected]',
    'phone_number' => '+15551234567'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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://mgmt-api.voxfra.com/v1/clients"

	payload := strings.NewReader("{\n  \"name\": \"ABC Motors\",\n  \"display_name\": \"ABC Motors - Downtown\",\n  \"type\": \"automotive\",\n  \"subscription_plan\": \"Pro\",\n  \"status\": \"active\",\n  \"contact_person\": \"Jane Smith\",\n  \"contact_email\": \"[email protected]\",\n  \"phone_number\": \"+15551234567\"\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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://mgmt-api.voxfra.com/v1/clients")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"ABC Motors\",\n  \"display_name\": \"ABC Motors - Downtown\",\n  \"type\": \"automotive\",\n  \"subscription_plan\": \"Pro\",\n  \"status\": \"active\",\n  \"contact_person\": \"Jane Smith\",\n  \"contact_email\": \"[email protected]\",\n  \"phone_number\": \"+15551234567\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://mgmt-api.voxfra.com/v1/clients")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"ABC Motors\",\n  \"display_name\": \"ABC Motors - Downtown\",\n  \"type\": \"automotive\",\n  \"subscription_plan\": \"Pro\",\n  \"status\": \"active\",\n  \"contact_person\": \"Jane Smith\",\n  \"contact_email\": \"[email protected]\",\n  \"phone_number\": \"+15551234567\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "ABC Motors Test Client",
    "display_name": "ABC Motors - Downtown",
    "type": "automotive",
    "subscription_plan": "pro",
    "contact_person": "<string>",
    "contact_email": "[email protected]",
    "phone_number": "<string>",
    "joined_at": "2023-11-07T05:31:56Z",
    "last_active_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": "Bad Request",
  "message": "name is required."
}

{
  "error": "Unauthorized"
}

{
  "error": "Conflict",
  "message": "A client with this name already exists in your organization."
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "Internal Server Error",
  "message": "Unexpected error"
}

Authorizations

X-API-Key

string

header

required

Your Voxfra management API key. Passed as a request header.

Format: vox_mgmt_<random>

Body

application/json

name

string

required

Display name of the client. Must be unique within your organization.

Required string length: 1 - 200

Example:

"ABC Motors"

type

string

required

Free-text business type identifier (e.g., automotive, medical).

Required string length: 1 - 100

Example:

"automotive"

subscription_plan

string

required

Subscription plan label. Currently UI-only metadata — the API does not yet enforce a fixed enum so partners can introduce new plan names without a schema migration. A canonical enum will be added once billing is wired in.

Required string length: 1 - 100

Example:

"Pro"

display_name

string

Optional public-facing label. Defaults to name when omitted.

Maximum string length: 255

Example:

"ABC Motors - Downtown"

status

enum<string>

default:active

Lifecycle state. Defaults to active when omitted.

Available options:

active,

inactive,

trial,

churned,

pending

contact_person

string

Maximum string length: 255

contact_email

string<email>

Maximum string length: 255

phone_number

string

7-15 digits with optional leading +. Whitespace, dashes, and parentheses are stripped before storage.

Example:

"+15551234567"

Response

Client created

data

object

Show child attributes

List Clients

List Calls

Getting Started

Changelog

Webhook Integration

Management API

Create Client

Authorizations

Body

Response