Create a customer

All customers created through the API are associated with the "api" channel.

post

Create a new customer.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

Bearer {apikey}

Path parameters

agentIdstringRequired

Body

application/json

firstNamestring · min: 1Optional

lastNamestring · min: 1Optional

aliasstringOptional

phoneNumberstring · min: 1Optional

emailstring · email · min: 1Optional

preferredLanguagestring · enumOptionalPossible values:

biostringOptional

dobstring · dateOptional

genderstringOptional

sexstring · enumOptionalPossible values:

pronounstringOptional

facebookProfileURLstring · uriOptional

instagramProfileURLstring · uriOptional

tiktokProfileURLstring · uriOptional

telegramProfileURLstring · uriOptional

photoURLstring · uriOptional

channelstring · enumOptionalPossible values:

tagsstring[]Optional

Responses

200

Successful Response

application/json

This an object representing a customer.

idstringOptional

phoneNumberstringOptional

firstNamestringOptional

lastNamestringOptional

aliasstringOptional

dobstring · dateOptional

pronounstringOptional

genderstringOptional

sexstring · enumOptionalPossible values:

preferredLanguagestringOptional

emailstringOptional

biostringOptional

photoURLstringOptional

facebookProfileURLstringOptional

instagramProfileURLstringOptional

tiktokProfileURLstringOptional

telegramProfileURLstringOptional

channelstringOptional

workplaceIdstringOptional

tagsstring[]Optional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

400

Bad Request

application/json

403

Forbidden

application/json

404

Not Found

application/json

409

Conflict

application/json

post

/v1/agents/{agentId}/customers

HTTPcURLJavaScriptPython

POST /v1/agents/{agentId}/customers HTTP/1.1
Host: api.voxity.ai
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 820

{
  "firstName": "text",
  "lastName": "text",
  "alias": "text",
  "phoneNumber": "text",
  "email": "[email protected]",
  "address": {
    "formatted": "text",
    "timezone": "text"
  },
  "preferredLanguage": "en",
  "bio": "text",
  "dob": "2026-04-02",
  "gender": "text",
  "sex": "male",
  "pronoun": "text",
  "facebookProfileURL": "https://example.com",
  "instagramProfileURL": "https://example.com",
  "tiktokProfileURL": "https://example.com",
  "telegramProfileURL": "https://example.com",
  "photoURL": "https://example.com",
  "channel": "voip",
  "tags": [
    "text"
  ],
  "instagram": {
    "id": "text",
    "username": "text"
  },
  "facebook": {
    "id": "text",
    "username": "text"
  },
  "whatsapp": {
    "id": "text",
    "username": "text"
  },
  "tiktok": {
    "id": "text",
    "username": "text"
  },
  "telegram": {
    "id": "text",
    "username": "text"
  },
  "widget_chatbot": {
    "id": "text",
    "username": "text",
    "chatbotId": "text"
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "id": "text",
  "phoneNumber": "text",
  "firstName": "text",
  "lastName": "text",
  "alias": "text",
  "dob": "2026-04-02",
  "pronoun": "text",
  "gender": "text",
  "sex": "male",
  "preferredLanguage": "text",
  "email": "text",
  "bio": "text",
  "photoURL": "text",
  "address": {
    "formatted": "text",
    "timezone": "text"
  },
  "facebookProfileURL": "text",
  "instagramProfileURL": "text",
  "tiktokProfileURL": "text",
  "telegramProfileURL": "text",
  "facebook": {
    "id": "text"
  },
  "instagram": {
    "id": "text",
    "username": "text"
  },
  "whatsapp": {
    "id": "text"
  },
  "tiktok": {
    "id": "text"
  },
  "telegram": {
    "id": "text"
  },
  "channel": "text",
  "workplaceId": "text",
  "tags": [
    "text"
  ],
  "phoneNumbers": [
    {
      "id": "text",
      "phoneNumber": "text",
      "type": "primary",
      "phoneType": "text",
      "lineType": "landline",
      "lineStatus": "active",
      "verified": true,
      "note": "text",
      "conversationSid": "text",
      "createdAt": "2026-04-02T06:22:05.870Z",
      "updatedAt": "2026-04-02T06:22:05.870Z"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "createdAt": "2026-04-02T06:22:05.870Z",
  "updatedAt": "2026-04-02T06:22:05.870Z"
}