Skip to main content
Base path: /audience

​
Types

// ============ 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;
}

​
Get all audiences

Searchable fields: name, description Sortable fields: name, createdAt, updatedAt 
curl -X GET https://api.gomobile.ma/api/audience?page=1&limit=20&search=VIP \
  -H "x-api-key: YOUR_API_KEY"
Response: 
{
  "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

curl -X GET https://api.gomobile.ma/api/audience/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
Response: 
{
  "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 
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: 
{
  "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

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: 
{
  "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

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: 
[
  "123e4567-e89b-12d3-a456-426614174000",
  "123e4567-e89b-12d3-a456-426614174001"
]

​
Update audience

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: 
{
  "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

curl -X DELETE https://api.gomobile.ma/api/audience/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
Response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  ...
}