Metigan Logometigan
REST APIAudiences

Audiences Endpoints

Create and manage audiences to organize your contacts into segmented lists.

POST/api/audiences

Create Audience

Create a new audience to organize contacts.

Request Body

FieldTypeRequiredDescription
namestringYesAudience name
descriptionstringNoAudience description

Example Request

curlTerminal
1
2
3
4
5
6
7
curl -X POST https://api.metigan.com/api/audiences \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers",
    "description": "Main newsletter subscriber list"
  }'

Response

201 CreatedJSON
1
2
3
4
5
6
7
8
9
10
11
{
  "success": true,
  "data": {
    "id": "aud_abc123",
    "name": "Newsletter Subscribers",
    "description": "Main newsletter subscriber list",
    "count": 0,
    "createdAt": "2024-01-19T10:30:00Z",
    "updatedAt": "2024-01-19T10:30:00Z"
  }
}
GET/api/audiences

List Audiences

Retrieve all audiences with pagination.

Query Parameters

ParameterTypeDescription
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20)

Example Request

curlTerminal
1
2
curl -X GET "https://api.metigan.com/api/audiences?page=1&limit=20" \
  -H "x-api-key: your_api_key"

Response

200 OKJSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "success": true,
  "audiences": [
    {
      "id": "aud_abc123",
      "name": "Newsletter Subscribers",
      "description": "Main newsletter subscriber list",
      "count": 5432,
      "createdAt": "2024-01-19T10:30:00Z"
    },
    {
      "id": "aud_def456",
      "name": "Customers",
      "description": "Paying customers",
      "count": 1234,
      "createdAt": "2024-01-15T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "limit": 20,
    "pages": 1
  }
}
GET/api/audiences/:id

Get Audience

Retrieve a single audience by ID.

Example Request

curlTerminal
1
2
curl -X GET https://api.metigan.com/api/audiences/aud_abc123 \
  -H "x-api-key: your_api_key"

Response

200 OKJSON
1
2
3
4
5
6
7
8
9
10
11
{
  "success": true,
  "data": {
    "id": "aud_abc123",
    "name": "Newsletter Subscribers",
    "description": "Main newsletter subscriber list",
    "count": 5432,
    "createdAt": "2024-01-19T10:30:00Z",
    "updatedAt": "2024-01-19T10:30:00Z"
  }
}
GET/api/audiences/:id/stats

Get Audience Statistics

Retrieve detailed statistics for an audience.

Example Request

curlTerminal
1
2
curl -X GET https://api.metigan.com/api/audiences/aud_abc123/stats \
  -H "x-api-key: your_api_key"

Response

200 OKJSON
1
2
3
4
5
6
7
8
9
10
11
12
{
  "success": true,
  "data": {
    "total": 5432,
    "subscribed": 5100,
    "unsubscribed": 250,
    "pending": 50,
    "bounced": 25,
    "complained": 7,
    "growthRate": 12.5
  }
}
PATCH/api/audiences/:id

Update Audience

Update an audience's name or description.

Example Request

curlTerminal
1
2
3
4
5
6
7
curl -X PATCH https://api.metigan.com/api/audiences/aud_abc123 \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Newsletter",
    "description": "Premium content subscribers"
  }'

Response

200 OKJSON
1
2
3
4
5
6
7
8
9
10
{
  "success": true,
  "data": {
    "id": "aud_abc123",
    "name": "Premium Newsletter",
    "description": "Premium content subscribers",
    "count": 5432,
    "updatedAt": "2024-01-19T14:00:00Z"
  }
}
DELETE/api/audiences/:id

Delete Audience

Delete an audience. Contacts in the audience will not be deleted.

Example Request

curlTerminal
1
2
curl -X DELETE https://api.metigan.com/api/audiences/aud_abc123 \
  -H "x-api-key: your_api_key"

Response

200 OKJSON
1
2
3
4
{
  "success": true,
  "message": "Audience deleted successfully"
}