> ## Documentation Index > Fetch the complete documentation index at: https://docs.brilo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Contact # Contact Service The Contact Service allows you to manage contacts in your workspace. You can create, read, update, and delete contacts. ## Create Contact Create a new contact in your workspace. ```http theme={null} POST /contact ``` ### Request Body | Field | Type | Required | Description | | ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | first\_name | string | No | Contact's first name | | last\_name | string | No | Contact's last name | | phone | string | Yes | Contact's phone number in E.164 format (e.g., +1234567890) | | email | string | No | Contact's email address | | additional\_notes | string | No | Additional notes about the contact | | custom\_fields | object | No | Custom field values keyed by the custom field keys defined in your workspace (Portal → Contacts → Custom Fields). Values are validated against each field definition; entries with unknown, archived, or reserved keys — or values failing type validation — are dropped and reported in `custom_field_warnings` (the contact is still created). Stored values can be referenced in agent prompts as `{{custom.}}`. | ### Example Request ```json theme={null} { "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "email": "john@example.com", "additional_notes": "VIP customer", "custom_fields": { "account_tier": "gold", "renewal_date": "2026-09-01" } } ``` ### Response ```json theme={null} { "status": 201, "data": { "id": "contact-123", "created_at": "2024-03-20T10:00:00Z", "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "email": "john@example.com", "additional_notes": "VIP customer", "status": "active", "updated_at": "2024-03-20T10:00:00Z", "workspace_id": "workspace-123", "custom_fields": { "account_tier": "gold", "renewal_date": "2026-09-01" } } } ``` If any `custom_fields` entries were dropped during validation, the response includes a top-level `custom_field_warnings` array describing each drop (codes: `unknown_key`, `archived_key`, `reserved_key`, `type_mismatch`, `option_invalid`, `too_long`, `empty_value`). ## Get Contact Retrieve a specific contact by ID. ```http theme={null} GET /contact/{id} ``` ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------- | | id | string | Yes | The ID of the contact to retrieve | ### Response ```json theme={null} { "id": "contact-123", "created_at": "2024-03-20T10:00:00Z", "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "email": "john@example.com", "additional_notes": "VIP customer", "status": "active", "updated_at": "2024-03-20T10:00:00Z", "workspace_id": "workspace-123", "custom_fields": { "account_tier": "gold", "renewal_date": "2026-09-01" } } ``` ## Update Contact Update an existing contact. ```http theme={null} PUT /contact/{id} ``` ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------- | | id | string | Yes | The ID of the contact to update | ### Request Body | Field | Type | Required | Description | | ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | first\_name | string | No | Contact's first name | | last\_name | string | No | Contact's last name | | phone | string | No | Contact's phone number in E.164 format | | email | string | No | Contact's email address | | additional\_notes | string | No | Additional notes about the contact | | custom\_fields | object | No | Custom field values to merge onto the contact. **Merge semantics:** keys you send are validated and written, keys you omit are left untouched, and a key set to `null` is removed. Unknown/archived/reserved keys and values failing type validation are dropped and reported in `custom_field_warnings` (the rest of the update still applies). | ### Example Request ```json theme={null} { "first_name": "John", "last_name": "Smith", "phone": "+1987654321", "email": "john.smith@example.com", "additional_notes": "Updated VIP customer", "custom_fields": { "account_tier": "platinum", "renewal_date": null } } ``` ### Response ```json theme={null} { "status": 200, "data": { "id": "contact-123", "created_at": "2024-03-20T10:00:00Z", "first_name": "John", "last_name": "Smith", "phone": "+1987654321", "email": "john.smith@example.com", "additional_notes": "Updated VIP customer", "status": "active", "updated_at": "2024-03-20T11:00:00Z", "workspace_id": "workspace-123", "custom_fields": { "account_tier": "platinum" } } } ``` As with Create, if any `custom_fields` entries were dropped during validation the response includes a top-level `custom_field_warnings` array describing each drop. ## Delete Contact Delete a contact from your workspace. ```http theme={null} DELETE /contact/{id} ``` ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------- | | id | string | Yes | The ID of the contact to delete | ### Response ```json theme={null} { "status": 200, "message": "Contact deleted successfully" } ```