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

# Audiences

> Group contacts into targetable audiences for campaigns

<Info>
  **Base path: `/audience`**
</Info>

## Types

<Accordion title="Type Definitions">
  ```typescript theme={null}
  // ============ Request Types ============

  interface CreateAudienceRequest {
    name: string;                 // 3-64 characters
    description?: string;         // max 256 characters
  }

  interface UpdateAudienceRequest {
    name?: string;                // 3-64 characters
    description?: string;         // 1-256 characters
  }

  interface AddContactsRequest {
    contacts: string[];           // Array of contact UUIDs
  }

  // ============ Query Parameters ============

  interface AudienceQueryParams {
    page?: number;                // default: 1, min: 1
    limit?: number;               // default: 20, max: 100
    search?: string;              // searches name, description
    sortBy?: string;              // name, createdAt, updatedAt
    sortOrder?: 'asc' | 'desc';   // default: 'desc'
  }

  interface AudienceContactsQueryParams {
    page?: number;                // default: 1, min: 1
    limit?: number;               // default: 20, max: 100
    search?: string;              // searches firstName, lastName, primaryPhone
    sortBy?: string;              // firstName, lastName, primaryPhone, createdAt
    sortOrder?: 'asc' | 'desc';   // default: 'desc'
  }

  // ============ Response Types ============

  interface AudienceResponse {
    id: string;
    organizationId: string;
    name: string;
    description: string | null;
    createdAt: string;            // ISO date
    updatedAt: string;            // ISO date
    deletedAt: string | null;     // ISO date (soft delete)
    createdBy: string | null;     // User UUID
    updatedBy: string | null;     // User UUID
    deletedBy: string | null;     // User UUID
  }

  interface PaginationMeta {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  }

  interface AudienceWithCountResponse extends AudienceResponse {
    contactCount: number;         // Number of contacts in this audience
  }

  interface AudienceListResponse {
    data: AudienceWithCountResponse[];
    meta: PaginationMeta;
  }
  ```
</Accordion>

### Get all audiences

**Searchable fields:** name, description

**Sortable fields:** name, createdAt, updatedAt

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/audience?page=1&limit=20&search=VIP \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "660e8400-e29b-41d4-a716-446655440001",
      "name": "VIP Customers",
      "description": "High-value customers for priority campaigns",
      "contactCount": 150,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}
```

***

### Get audience by ID

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/audience/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "VIP Customers",
  "description": "High-value customers for priority campaigns",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
```

***

### Get paginated list of contacts belonging to an audience

**Searchable fields:** firstName, lastName, primaryPhone

**Sortable fields:** firstName, lastName, primaryPhone, createdAt

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/audience/550e8400-e29b-41d4-a716-446655440000/contacts?page=1&limit=20&search=john \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "660e8400-e29b-41d4-a716-446655440001",
      "firstName": "John",
      "lastName": "Doe",
      "primaryPhone": "+1234567890",
      "primaryEmail": "john@example.com",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}
```

***

### Create a new audience

```bash theme={null}
curl -X POST https://api.gomobile.ma/api/audience \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "name": "VIP Customers",
  "description": "High-value customers for priority campaigns"
}
'
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "VIP Customers",
  "description": "High-value customers for priority campaigns",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
```

***

### Add multiple contacts to an audience segment

```bash theme={null}
curl -X POST https://api.gomobile.ma/api/audience/550e8400-e29b-41d4-a716-446655440000/add-contacts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "contacts": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ]
}
'
```

Response:

```json theme={null}
[
  "123e4567-e89b-12d3-a456-426614174000",
  "123e4567-e89b-12d3-a456-426614174001"
]
```

***

### Update audience

```bash theme={null}
curl -X PUT https://api.gomobile.ma/api/audience/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "name": "Updated VIP Customers",
  "description": "Updated description"
}
'
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Updated VIP Customers",
  "description": "Updated description",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T12:00:00.000Z"
}
```

***

### Delete audience

```bash theme={null}
curl -X DELETE https://api.gomobile.ma/api/audience/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  ...
}
```