Data Types

This page is the single source of truth for every field on every object you can see in the Xobito API and in outbound webhooks.

Conventions

Type	Example	Notes
`integer`	`25`	Database primary keys are positive integers.
`string`	`"John"`	UTF-8.
`boolean`	`true`	Booleans are true/false JSON literals.
`datetime`	`"2026-04-08T14:30:25.000000Z"`	ISO-8601, UTC, microsecond precision.
`array<T>`	`[1, 2, 3]`	Homogeneous array.
`object`	`{ "key": "value" }`	Free-form JSON object.
`nullable T`	`null` or `T`	Field may be omitted/null.

Response envelope

Every successful response is wrapped:

{
  "status": "success",
  "data": { ... },
  "message": "Optional human-readable message"
}

Pagination envelope

List endpoints use Laravel’s paginator shape, nested inside data:

{
  "status": "success",
  "data": {
    "current_page": 1,
    "data": [ /* the actual items */ ],
    "per_page": 15,
    "total": 100,
    "last_page": 7,
    "first_page_url": "https://dash.xobito.com/api/v1/acme/contacts?page=1",
    "next_page_url":  "https://dash.xobito.com/api/v1/acme/contacts?page=2",
    "prev_page_url":  null,
    "from": 1,
    "to": 15,
    "path": "https://dash.xobito.com/api/v1/acme/contacts",
    "links": [ { "url": "...", "label": "...", "active": false } ]
  }
}

Field	Type	Notes
`current_page`	integer	1-indexed.
`data`	array	The page’s items.
`per_page`	integer	Default `15`, max `100`.
`total`	integer	Total matching rows.
`last_page`	integer	Final page number.
`first_page_url` / `next_page_url` / `prev_page_url`	nullable string	URLs for navigation.
`from` / `to`	integer	1-indexed range of items on this page.

Contact

Field	Type	Notes
`id`	integer	Primary key.
`tenant_id`	integer	Your workspace id.
`firstname`	string	Note: `firstname`, not `first_name`.
`lastname`	nullable string	Note: `lastname`.
`company`	nullable string
`type`	string	Enum: `lead`, `customer`, `guest`. The API only accepts `lead` or `customer` on writes.
`description`	nullable string
`country_id`	nullable integer	FK to the countries table.
`zip`	nullable string
`city`	nullable string
`state`	nullable string
`address`	nullable string
`assigned_id`	nullable integer	User id of the owner.
`status_id`	integer	FK to a Status.
`source_id`	integer	FK to a Source.
`email`	nullable string	Unique per tenant when present.
`website`	nullable string
`phone`	string	Required, unique per tenant.
`is_enabled`	boolean
`is_opted_out`	boolean
`addedfrom`	nullable integer	User id who added the contact.
`dateassigned`	nullable datetime
`opted_out_date`	nullable datetime
`last_status_change`	nullable datetime
`default_language`	nullable string	IANA language code.
`group_id`	array of integers	JSON array of Group ids.
`custom_fields_data`	object	Free-form key/value.
`created_at`	datetime
`updated_at`	datetime

Example

{
  "id": 25,
  "tenant_id": 13,
  "firstname": "John",
  "lastname": "Doe",
  "company": "Demo Co",
  "type": "lead",
  "email": "john@example.com",
  "phone": "+1234567890",
  "source_id": 2,
  "status_id": 1,
  "country_id": 101,
  "group_id": [1, 2],
  "is_enabled": 1,
  "is_opted_out": 0,
  "custom_fields_data": {},
  "created_at": "2026-04-08T14:30:25.000000Z",
  "updated_at": "2026-04-08T14:30:25.000000Z"
}

Status

A labeled state you can apply to contacts.

Field	Type	Notes
`id`	integer
`tenant_id`	integer
`name`	string	Unique per tenant. 3–255 chars.
`color`	nullable string	Hex colour, max 7 chars (e.g. `#FF0000`).
`isdefault`	boolean	Whether new contacts default to this status.
`created_at`	datetime
`updated_at`	datetime

Source

Where a contact came from (e.g. “Website Form”).

Field	Type	Notes
`id`	integer
`tenant_id`	integer
`name`	string	Unique per tenant. 1–255 chars.
`created_at`	datetime
`updated_at`	datetime

Sources have no color field.

Group

A grouping for contacts. A contact’s memberships are stored in its group_id array.

Field	Type	Notes
`id`	integer
`tenant_id`	integer
`name`	string	Unique per tenant.
`created_at`	datetime
`updated_at`	datetime

WhatsApp Template

A Meta-approved message template.

Field	Type	Notes
`id`	integer	Xobito’s id.
`tenant_id`	integer
`template_id`	string	Meta’s template id.
`template_name`	string
`language`	string	IANA tag (e.g. `en_US`).
`status`	string	`DRAFT`, `PENDING`, `APPROVED`, or `REJECTED`.
`category`	string	`MARKETING` or `UTILITY`.
`header_data_format`	nullable string	`TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT`, or `null`.
`header_data_text`	nullable string
`header_params_count`	integer
`body_data`	string	Template body text (with `{{n}}` placeholders).
`body_params_count`	integer
`footer_data`	nullable string
`footer_params_count`	integer
`buttons_data`	nullable array	JSON-encoded button definitions.
`header_file_url`	nullable string
`header_variable_value`	nullable string
`body_variable_value`	nullable string
`template_type`	nullable string
`cards_json`	nullable array	For carousel templates.
`created_at`	datetime
`updated_at`	datetime

Only templates with status: "APPROVED" can be sent through POST /messages/template.

API Token

The record behind the apitk_... tokens issued in Settings → API Management.

Field	Type	Notes
`id`	integer
`tenant_id`	integer
`name`	string	Human-readable label.
`abilities`	array of strings	See Authentication.
`rate_limits`	nullable object	Per-token rate-limit overrides.
`monthly_quota`	nullable integer	Optional monthly call cap.
`expires_at`	nullable datetime	`null` = never expires.
`is_active`	boolean	Revoked tokens have this set to `false`.
`created_at`	datetime
`updated_at`	datetime

The plaintext token itself is never returned by the API after creation — only the record metadata. Store the plaintext from the dashboard the moment it is generated.

Webhook Configuration

Not exposed as an API resource — set in Settings → Webhook Settings. Shown here for reference.

Field	Type	Notes
`webhook_enabled`	boolean
`webhook_url`	string	Single URL that receives all configured events.
`contacts_actions`	array of strings	Subset of `["create","update","delete"]`.
`status_actions`	array of strings	Subset of `["create","update","delete"]`.
`source_actions`	array of strings	Subset of `["create","update","delete"]`.

Webhook Payload

Every outbound webhook POST uses this shape.

Field	Type	Notes
`event`	string	`"created"`, `"updated"`, or `"deleted"`.
`model`	string	Fully qualified PHP class — e.g. `App\Models\Tenant\Contact`.
`data.id`	integer	Primary key of the subject record.
`data.attributes`	object	Snapshot of all attributes at the time of the event.
`data.relations`	object	Reserved for eager-loaded relations, usually `{}`.
`original`	nullable object	Usually `null`.
`timestamp`	datetime	ISO-8601 with offset.

Message send response

The shape returned by send-text / send-template / send-media endpoints.

Field	Type	Notes
`message_id`	string	WhatsApp `wamid.*`.
`contact_id`	integer	Xobito contact id the message was sent to.
`phone`	string	Recipient E.164 phone number.
`message`	nullable string	The message body that was sent (text).
`status`	string	Initial WhatsApp status — typically `sent`.
`sent_at`	datetime
`chat_id`	integer	Internal chat id.
`contact_created`	boolean	`true` if the contact was auto-created from the send.

Message status response

Returned by GET /messages/{messageId}/status.

Field	Type	Notes
`message_id`	string	The WhatsApp `wamid.*`.
`delivery_status`	string	`pending`, `sent`, `delivered`, `read`, or `failed`.
`error_message`	nullable string	Populated when `delivery_status: "failed"`.
`source`	string	Where the status record came from (e.g. `chat`).
`last_updated`	datetime	Last time WhatsApp updated this status.
`statuses`	object	Dictionary of every possible status with human descriptions.

Phone validation response

Returned by POST /phone/validate.

Field	Type	Notes
`phone`	string	Original input, normalised with leading `+`.
`phone_digits`	string	Digits only.
`format_valid`	boolean	Whether the number is a valid E.164 format.
`country_code`	nullable string	Numeric calling code, e.g. `"91"`.
`country`	nullable string	English country name.
`national_number`	nullable string	Subscriber number without country code.
`e164`	nullable string	Normalised E.164 form.
`reason`	nullable string	Failure reason when `format_valid: false`.
`note`	string	Static note about the check’s scope.

Phone validation confirms format only. It does not check whether the number is registered on WhatsApp.

Introduction

API Reference

Webhooks

Data Types

Conventions

Response envelope

Contact

Example

Status

Source

Group

WhatsApp Template

API Token

Webhook Configuration

Webhook Payload

Message send response

Message status response

Phone validation response

Introduction

API Reference

Webhooks

Data Types

​Conventions

​Response envelope

​Pagination envelope

​Contact

​Example

​Status

​Source

​Group

​WhatsApp Template

​API Token

​Webhook Configuration

​Webhook Payload

​Message send response

​Message status response

​Phone validation response

Conventions

Response envelope

Pagination envelope

Contact

Example

Status

Source

Group

WhatsApp Template

API Token

Webhook Configuration

Webhook Payload

Message send response

Message status response

Phone validation response