> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Managing customer contacts and their roles within accounts

Contacts represent individuals associated with an account in the Thena platform. They serve as the key points of communication and relationship management between your organization and your customers.

## Understanding contacts

<CardGroup cols={1}>
  <Card title="Core purpose" icon="address-book">
    Contacts provide a structured way to manage relationships with individuals within customer organizations. Each contact can have specific roles, responsibilities, and preferences that help in personalizing interactions.
  </Card>
</CardGroup>

## Contact roles

<CardGroup cols={2}>
  <Card title="Primary roles" icon="user-tie">
    • Primary contact: Main decision maker <br />
    • Billing contact: Financial matters <br />
    • Technical contact: Implementation and support <br />
    • Executive sponsor: Strategic relationship <br />
  </Card>

  <Card title="Supporting roles" icon="users">
    • Department heads <br />
    • Team managers <br />
    • Project leads <br />
    • Subject matter experts <br />
  </Card>
</CardGroup>

## Standard fields

### Required fields

| Name                 | Type    | Options                                                                  | Comments                            |
| :------------------- | :------ | :----------------------------------------------------------------------- | :---------------------------------- |
| Organization ID      | string  | Required                                                                 | Organization the contact belongs to |
| First Name           | string  | Required                                                                 | Contact's first name                |
| Email                | string  | Required, Unique per organization                                        | Primary email address               |
| Contact Type         | string  | Required, Values: \[PRIMARY (default), BILLING, LEGAL, EXECUTIVE, OTHER] | Type of contact relationship        |
| Is Marketing Contact | boolean | Required, Default: false                                                 | Marketing communication preference  |
| Is Active            | boolean | Required, Default: true                                                  | Contact's active status             |

### Optional fields

| Name             | Type   | Options          | Comments                       |
| :--------------- | :----- | :--------------- | :----------------------------- |
| Last Name        | string | Optional         | Contact's last name            |
| Phone Number     | string | Optional         | Phone number with country code |
| Avatar URL       | string | Optional         | Profile picture URL            |
| Metadata         | jsonb  | Optional         | Additional metadata            |
| Customer User ID | string | Optional, Unique | Associated user reference      |

### System-managed fields

| Name       | Type      | Options        | Comments                            |
| :--------- | :-------- | :------------- | :---------------------------------- |
| Contact ID | bigserial | Auto-generated | Primary key                         |
| UID        | text      | Auto-generated | Unique identifier (ULID)            |
| Created At | timestamp | Auto-populated | Creation timestamp with timezone    |
| Updated At | timestamp | Auto-populated | Last update timestamp with timezone |
| Deleted At | timestamp | Optional       | Soft delete timestamp with timezone |

<Note>
  Database types:

  * Organization ID and Customer User ID are stored as `bigint` in the database
  * First Name, Last Name, Email, Phone Number are stored as `text`
  * Metadata is stored as `jsonb`
  * System fields use their respective database types (`bigserial`, `text`, `boolean`, `timestamp with time zone`)
</Note>

## Best practices

<Steps>
  <Step title="Contact information management">
    * Maintain up-to-date contact details
    * Verify email addresses periodically
    * Document communication preferences
    * Track role changes
  </Step>

  <Step title="Role assignment">
    * Clearly define primary contacts
    * Maintain backup contacts
    * Document role transitions
    * Update access permissions
  </Step>

  <Step title="Communication">
    * Respect time zones
    * Follow language preferences
    * Maintain communication history
    * Track engagement levels
  </Step>
</Steps>

## API endpoints

### Sample contact

```json theme={null}
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@acme.com",
  "phone": "+1-555-123-4567",
  "type": "PRIMARY",
  "isMarketingContact": false,
  "isActive": true,
  "metadata": {
    "department": "Engineering",
    "title": "CTO",
    "timezone": "America/Los_Angeles"
  }
}
```

<Note>
  When creating a contact, the system will add additional fields in the response such as `uid`, `createdAt`, `updatedAt`, and `accountId`.
</Note>

### Available operations

<Accordion title="Contact management" icon="address-book">
  ```bash theme={null}
  # List account contacts
  GET /v1/accounts/{accountId}/contacts

  # Create account contact
  POST /v1/accounts/{accountId}/contacts
  Content-Type: application/json

  # Get contact by ID
  GET /v1/accounts/{accountId}/contacts/{contactId}

  # Update contact
  PATCH /v1/accounts/{accountId}/contacts/{contactId}
  Content-Type: application/json

  # Delete contact
  DELETE /v1/accounts/{accountId}/contacts/{contactId}
  ```

  <Note>
    All endpoints require authentication with Bearer token, API key, and Organization ID in the headers.
  </Note>

  For detailed API specifications, see <a href="/api-reference/platform/accounts/contacts" target="_blank">Contact Management</a>
</Accordion>

## Related resources

<CardGroup cols={2}>
  <Card title="Accounts overview" icon="building-user" href="/platform/core-concepts/accounts/overview">
    Learn about account management
  </Card>

  <Card title="Activities" icon="calendar-days" href="/platform/core-concepts/accounts/activities">
    Track interactions with contacts
  </Card>
</CardGroup>