> ## Documentation Index > Fetch the complete documentation index at: https://documents.xobito.com/llms.txt > Use this file to discover all available pages before exploring further. # Data Types > Canonical schema for every object exposed by the Xobito API. 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` | `[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: ```json theme={null} { "status": "success", "data": { ... }, "message": "Optional human-readable message" } ``` ## Pagination envelope List endpoints use Laravel's paginator shape, nested inside `data`: ```json theme={null} { "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](#status). | | `source_id` | integer | FK to a [Source](#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 | *(schema reserved — not currently set or returned by the API)* | | `addedfrom` | nullable integer | User id who added the contact. | | `dateassigned` | nullable datetime | | | `opted_out_date` | nullable datetime | *(schema reserved — not currently set or returned by the API)* | | `last_status_change` | nullable datetime | | | `default_language` | nullable string | IANA language code. | | `group_id` | array of integers | JSON array of [Group](#group) ids. | | `custom_fields_data` | object | Free-form key/value. | | `created_at` | datetime | | | `updated_at` | datetime | | ### Example ```json theme={null} { "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 | *(schema reserved — not currently set or returned by the API)* | | `cards_json` | nullable array | *(schema reserved — not currently set or returned by the API; carousel templates are not supported)* | | `created_at` | datetime | | | `updated_at` | datetime | | Only templates with `status: "APPROVED"` can be sent through [`POST /messages/template`](/api-reference/endpoints/send-template-message). ## API Token API tokens are not exposed as an object via the API. Each workspace has a single token managed in **Settings → API Management**. See [Authentication](/developers/authentication). ## 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` | object | Per-action flags — `{ "create": bool, "update": bool, "delete": bool }`. | | `status_actions` | object | Same shape as `contacts_actions`. | | `source_actions` | object | Same shape as `contacts_actions`. | Example: ```json theme={null} "contacts_actions": { "create": true, "update": true, "delete": false } ``` ## 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`](/api-reference/endpoints/message-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`](/api-reference/endpoints/validate-phone). | 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.